From f463cc922987111ccbc73e8b28b7cebf18483930 Mon Sep 17 00:00:00 2001 From: Ukendio Date: Sat, 3 Jan 2026 17:27:35 +0100 Subject: [PATCH] Add some documentation to the exported functions --- .github/workflows/build-studio-docs.yaml | 0 scripts/alias_resolver.luau | 0 scripts/build_studio_docs.luau | 0 src/jecs.luau | 30 +++++++++++++++++++++--- studio_docs.project.json | 0 5 files changed, 27 insertions(+), 3 deletions(-) mode change 100644 => 100755 .github/workflows/build-studio-docs.yaml mode change 100644 => 100755 scripts/alias_resolver.luau mode change 100644 => 100755 scripts/build_studio_docs.luau mode change 100644 => 100755 studio_docs.project.json diff --git a/.github/workflows/build-studio-docs.yaml b/.github/workflows/build-studio-docs.yaml old mode 100644 new mode 100755 diff --git a/scripts/alias_resolver.luau b/scripts/alias_resolver.luau old mode 100644 new mode 100755 diff --git a/scripts/build_studio_docs.luau b/scripts/build_studio_docs.luau old mode 100644 new mode 100755 diff --git a/src/jecs.luau b/src/jecs.luau index 4ce648e..24f79ca 100755 --- a/src/jecs.luau +++ b/src/jecs.luau @@ -3486,7 +3486,7 @@ local function world_new(DEBUG: boolean?) if idr_t then local archetype_ids = idr_t.records local to_remove = {}:: { [i53]: componentrecord} - + for archetype_id in archetype_ids do local idr_t_archetype = archetypes[archetype_id] local idr_t_types = idr_t_archetype.types @@ -3522,7 +3522,7 @@ local function world_new(DEBUG: boolean?) if deleted_any then continue end - + if remove_count == 1 then local id, id_record = next(to_remove) local to_u = archetype_traverse_remove(world, id :: i53, idr_t_archetype) @@ -3877,44 +3877,66 @@ local function ecs_entity_record(world: world, entity: i53) end return { + --- Create the world world = world_new :: (boolean?) -> World, World = { new = world_new }, component = (ECS_COMPONENT :: any) :: () -> Entity, tag = (ECS_TAG :: any) :: () -> Entity, + --- Give the preregistered ID some data meta = (ECS_META :: any) :: (id: Entity, id: Component, value: a?) -> Entity, + --- Check if the ID is a tag is_tag = (ecs_is_tag :: any) :: (World, Component) -> boolean, + --- OnAdd Hook to detect added components (see more how_to/110_hooks.luau) OnAdd = (EcsOnAdd :: any) :: Component<(entity: Entity, id: Id, data: T) -> ()>, - OnRemove = (EcsOnRemove :: any) :: Component<(entity: Entity, id: Id, delete: boolean?) -> ()>, + --- OnRemove Hook to detect removed components (see more how_to/110_hooks.luau) + OnRemove = (EcsOnRemove :: any) :: Component<(entity: Entity, id: Id) -> ()>, + --- OnChange Hook to detect mutations (see more how_to/110_hooks.luau) OnChange = (EcsOnChange :: any) :: Component<(entity: Entity, id: Id, data: T) -> ()>, + --- Relationship to define the parent of an entity ChildOf = (EcsChildOf :: any) :: Entity, + --- This marks an ID as a component and can therefore have data (see more how_to/010_how_components_work.luau) Component = (EcsComponent :: any) :: Entity, + --- Used for querying relationships of any target (see more how_to/041_entity_relationships.luau) Wildcard = (EcsWildcard :: any) :: Component, + --- Alias for jecs.Wildcard w = (EcsWildcard :: any) :: Component, + --- OnDelete Cleanup condition (see more 100_cleanup_traits) OnDelete = (EcsOnDelete :: any) :: Entity, + --- OnDeleteTarget Cleanup condition (see more 100_cleanup_traits) OnDeleteTarget = (EcsOnDeleteTarget :: any) :: Entity, + --- Delete Cleanup action (see more 100_cleanup_traits) Delete = (EcsDelete :: any) :: Entity, + --- Remove Cleanup action (see more 100_cleanup_traits) Remove = (EcsRemove :: any) :: Entity, + --- This can be used to name your components with, either as some discriminant or for debugging purposes Name = (EcsName :: any) :: Component, + --- Used to mark whether a relationship is exclusive or not (see more 041_entity_relationships.luau) Exclusive = (EcsExclusive :: any) :: Entity, ArchetypeCreate = (EcsOnArchetypeCreate :: any) :: Entity, ArchetypeDelete = (EcsOnArchetypeDelete :: any) :: Entity, Rest = (EcsRest :: any) :: Entity, + --- Create a pair between two components pair = ECS_PAIR :: (first: Entity

, second: Entity) -> Pair, + --- To check if a component is a pair IS_PAIR = ECS_IS_PAIR :: (pair: Component) -> boolean, ECS_PAIR_FIRST = ECS_PAIR_FIRST :: (pair: Id

) -> Component

, ECS_PAIR_SECOND = ECS_PAIR_SECOND :: (pair: Id

) -> Component, + --- Lookup the first element in a pair pair_first = ecs_pair_first :: (world: World, pair: Id

) -> Component

, + --- Lookup the second element in a pair pair_second = ecs_pair_second :: (world: World, pair: Id

) -> Component, entity_index_get_alive = entity_index_get_alive, archetype_append_to_records = archetype_append_to_records, id_record_ensure = id_record_ensure :: (World, Component) -> ComponentRecord, + --- Grabs metadata on the component component_record = id_record_get :: (World, Component) -> ComponentRecord?, + --- Grabs metadata on the entity record = ecs_entity_record :: (World, Entity) -> Record, archetype_create = archetype_create :: (World, { Component }, string) -> Archetype, @@ -3925,7 +3947,9 @@ return { create_edge_for_remove = create_edge_for_remove, archetype_traverse_add = archetype_traverse_add :: (World, Component, Archetype) -> Archetype, archetype_traverse_remove = archetype_traverse_remove :: (World, Component, Archetype) -> Archetype, + --- For bulk inserting components to an entity bulk_insert = ecs_bulk_insert :: (World, Entity, { Component }, { any }) -> (), + --- For bulk removing components from an entity bulk_remove = ecs_bulk_remove :: (World, Entity, { Component }) -> (), entity_move = entity_move :: (EntityIndex, Entity, Record, Archetype) -> (), diff --git a/studio_docs.project.json b/studio_docs.project.json old mode 100644 new mode 100755