diff --git a/benches/query.luau b/benches/query.luau index f715d47..54cc7d4 100644 --- a/benches/query.luau +++ b/benches/query.luau @@ -40,11 +40,6 @@ do end end) - BENCH("1 component, 7 tags", function() - for _ in world:query(H):with(G, F, E, D, C, B, A) do - end - end) - local e = world:entity() world:set(e, A, true) world:set(e, B, true) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 2660dde..e9184b7 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -9,6 +9,7 @@ export default defineConfig({ // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, +<<<<<<< HEAD { text: 'Examples', link: '/markdown-examples' } ], @@ -50,6 +51,59 @@ export default defineConfig({ } ], +======= + { text: 'Examples', link: '/markdown-examples' }, + { text: 'API', link: '/api/jecs.md' } + ], + + sidebar: { + "/api/": [ + { + text: "API reference", + items: [ + { text: "jecs", link: "/api/jecs" }, + { text: "World", link: "/api/world" }, + { text: "Query", link: "/api/query" } + ] + } + ], + "/learn/": [ + { + text: "Introduction", + items: [ + { text: 'Getting Started', link: '/overview/get-started' }, + { text: 'First Jecs Project', link: '/overview/first-jecs-project' } + ] + }, + { + text: 'Concepts', + items: [ + { text: 'Entities', link: '/concepts/entities' }, + { text: 'Static Components', link: '/concepts/static-components' }, + { text: 'Queries', link: '/concepts/queries' }, + ] + }, + { + text: "FAQ", + items: [ + { text: 'How can I contribute?', link: '/faq/contributing' } + ] + }, + + ], + "/contributing/": [ + { + text: 'Contributing', + items: [ + { text: 'Contribution Guidelines', link: '/contributing/guidelines' }, + { text: 'Submitting Issues', link: '/contributing/issues' }, + { text: 'Submitting Pull Requests', link: '/contributing/pull-requests' }, + ] + } + ] + }, + +>>>>>>> a3eb2cddc35a58d42ed468f8a5806597f709345e socialLinks: [ { icon: 'github', link: 'https://github.com/vuejs/vitepress' } ] diff --git a/docs/api/jecs.md b/docs/api/jecs.md new file mode 100644 index 0000000..61a66a8 --- /dev/null +++ b/docs/api/jecs.md @@ -0,0 +1,30 @@ +# Jecs + +Jecs. Just an Entity Component System. + +## Properties + +### World +```luau +jecs.World: World +``` + +### Wildcard + +### z<> + +## Functions + +### pair() +```luau +function jecs.pair( + first: Entity, -- The first element of the pair, referred to as the relationship of the relationship pair. + object: Entity, -- The second element of the pair, referred to as the target of the relationship pair. +): number -- Returns the Id with those two elements + +``` +::: info + +Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding. + +::: diff --git a/docs/api/world.md b/docs/api/world.md index 96f7fb3..e7702fa 100644 --- a/docs/api/world.md +++ b/docs/api/world.md @@ -1,11 +1,11 @@ -# World +# Query A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components. ## Functions ### new() -```lua +```luau function World.new(): World ``` Creates a new world. @@ -27,7 +27,7 @@ const world = new World(); ## entity() ```luau -function World:entity(): Entity +function World:entity(): Entity -- The new entit. ``` Creates a new entity. @@ -42,11 +42,12 @@ local entity = world:entity() const entity = world.entity(); ``` -::: +:: +: -### component()` +### component() ```luau -function World:component(): Entity +function World:component(): Entity -- The new componen. ``` Creates a new component. @@ -60,7 +61,6 @@ local Health = world:component() :: jecs.Entity ```ts [typescript] const Health = world.component(); ``` - ::: ::: info @@ -68,3 +68,65 @@ You should use this when creating components. For example, a Health type should be created using this. ::: + +### get() +```luau +function World:get( + entity: Entity, -- The entity + ...: Entity -- The types to fetch +): ... -- Returns the component data in the same order they were passed in +``` +Returns the data for each provided type for the corresponding entity. + +::: + +### add() +```luau +function World:add( + entity: Entity, -- The entity + id: Entity -- The component ID to add +): () +``` +Adds a component ID to the entity. + +This operation adds a single (component) id to an entity. + +::: info +This function is idempotent, meaning if the entity already has the id, this operation will have no side effects. +::: + + +### set() +```luau +function World:set( + entity: Entity, -- The entity + id: Entity, -- The component ID to set + data: T -- The data of the component's type +): () +``` +Adds or changes the entity's component. + +### query() +```luau +function World:query( + ...: Entity -- The component IDs to query with. Entities that satifies the conditions will be returned +): Query<...Entity> -- Returns the Query which gets the entity and their corresponding data when iterated +``` +Creates a [`query`](query) with the given component IDs. + +Example: +::: code-group + +```luau [luau] +for id, position, velocity in world:query(Position, Velocity) do + -- Do something +end +``` + +```ts [typescript] +for (const [id, position, velocity] of world.query(Position, Velocity) { + // Do something +} +``` + +::: diff --git a/docs/concepts/queries.md b/docs/concepts/queries.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/concepts/queries.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/concepts/static-components.md b/docs/concepts/static-components.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/concepts/static-components.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/faq/contributing.md b/docs/faq/contributing.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/faq/contributing.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 953fa01..3ed3a93 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ hero: link: /overview/get-started.md - theme: alt text: API References - link: /api/ + link: /api/jecs.md features: - title: Stupidly Fast diff --git a/docs/concepts/entities.md b/docs/learn/concepts/entities.md similarity index 50% rename from docs/concepts/entities.md rename to docs/learn/concepts/entities.md index d3f5a12..8b13789 100644 --- a/docs/concepts/entities.md +++ b/docs/learn/concepts/entities.md @@ -1 +1 @@ - + diff --git a/docs/learn/concepts/queries.md b/docs/learn/concepts/queries.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/concepts/queries.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/concepts/static-components.md b/docs/learn/concepts/static-components.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/concepts/static-components.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/faq/contributing.md b/docs/learn/faq/contributing.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/faq/contributing.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/overview/first-jecs-project.md b/docs/learn/overview/first-jecs-project.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/overview/first-jecs-project.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/overview/get-started.md b/docs/learn/overview/get-started.md similarity index 95% rename from docs/overview/get-started.md rename to docs/learn/overview/get-started.md index ee09bc0..e7714bb 100644 --- a/docs/overview/get-started.md +++ b/docs/learn/overview/get-started.md @@ -1,130 +1,130 @@ -# Getting Started - -## Installation - -### Installing Standalone - -Navigate to the [releases page](https://github.com/Ukendio/jecs/releases) and download `jecs.rbxm` from the assets. - -![jecs.rbxm](rbxm.png) - -### Using Wally - -Add the following to your wally configuration: - -::: code-group - -```toml [wally.toml] -jecs = "ukendio/jecs@0.2.3" -``` - -::: - -### Using npm (roblox-ts) - -Use one of the following commands on your root project directory: - -::: code-group -```bash [npm] -npm i https://github.com/Ukendio/jecs.git -``` -```bash [yarn] -yarn add https://github.com/Ukendio/jecs.git -``` -```bash [pnpm] -pnpm add https://github.com/Ukendio/jecs.git -``` - -::: - -## Example Usage - -::: code-group - -```luau [Luau] -local world = jecs.World.new() -local pair = jecs.pair -local Wildcard = jecs.Wildcard - -local Name = world:component() - -local function getName(e) - return world:get(e, Name) -end - -local Eats = world:component() - --- Relationship objects -local Apples = world:component() --- components are entities, so you can add components to components -world:set(Apples, Name, "apples") -local Oranges = world:component() -world:set(Oranges, Name, "oranges") - -local bob = world:entity() --- Pairs can be constructed from two entities - -world:set(bob, pair(Eats, Apples), 10) -world:set(bob, pair(Eats, Oranges), 5) -world:set(bob, Name, "bob") - -local alice = world:entity() -world:set(alice, pair(Eats, Apples), 4) -world:set(alice, Name, "alice") - -for id, amount in world:query(pair(Eats, Wildcard)) do - -- get the second target of the pair - local food = world:target(id, Eats) - print(string.format("%s eats %d %s", getName(id), amount, getName(food))) -end - --- Output: --- bob eats 10 apples --- bob eats 5 pears --- alice eats 4 apples -``` - - -```ts [Typescript] -import { Wildcard, pair, World } from "@rbxts/jecs" - - -const world = new World() -const Name = world.component() -function getName(e) { - return world.get(e, Name) -} - -const Eats = world.component() - -// Relationship objects -const Apples = world.component() -// components are entities, so you can add components to components -world.set(Apples, Name, "apples") -const Oranges = world.component() -world.set(Oranges, Name, "oranges") - -const bob = world.entity() -// Pairs can be constructed from two entities - -world.set(bob, pair(Eats, Apples), 10) -world.set(bob, pair(Eats, Oranges), 5) -world.set(bob, Name, "bob") - -const alice = world.entity() -world.set(alice, pair(Eats, Apples), 4) -world.set(alice, Name, "alice") - -for (const [id, amount] of world.query(pair(Eats, Wildcard))) { - // get the second target of the pair - const food = world:target(id, Eats) - print(string.format("%s eats %d %s", getName(id), amount, getName(food))) -} - -// Output: -// bob eats 10 apples -// bob eats 5 pears -// alice eats 4 apples - -``` - +# Getting Started + +## Installation + +### Installing Standalone + +Navigate to the [releases page](https://github.com/Ukendio/jecs/releases) and download `jecs.rbxm` from the assets. + +![jecs.rbxm](rbxm.png) + +### Using Wally + +Add the following to your wally configuration: + +::: code-group + +```toml [wally.toml] +jecs = "ukendio/jecs@0.2.3" +``` + +::: + +### Using npm (roblox-ts) + +Use one of the following commands on your root project directory: + +::: code-group +```bash [npm] +npm i https://github.com/Ukendio/jecs.git +``` +```bash [yarn] +yarn add https://github.com/Ukendio/jecs.git +``` +```bash [pnpm] +pnpm add https://github.com/Ukendio/jecs.git +``` + +::: + +## Example Usage + +::: code-group + +```luau [Luau] +local world = jecs.World.new() +local pair = jecs.pair +local Wildcard = jecs.Wildcard + +local Name = world:component() + +local function getName(e) + return world:get(e, Name) +end + +local Eats = world:component() + +-- Relationship objects +local Apples = world:component() +-- components are entities, so you can add components to components +world:set(Apples, Name, "apples") +local Oranges = world:component() +world:set(Oranges, Name, "oranges") + +local bob = world:entity() +-- Pairs can be constructed from two entities + +world:set(bob, pair(Eats, Apples), 10) +world:set(bob, pair(Eats, Oranges), 5) +world:set(bob, Name, "bob") + +local alice = world:entity() +world:set(alice, pair(Eats, Apples), 4) +world:set(alice, Name, "alice") + +for id, amount in world:query(pair(Eats, Wildcard)) do + -- get the second target of the pair + local food = world:target(id, Eats) + print(string.format("%s eats %d %s", getName(id), amount, getName(food))) +end + +-- Output: +-- bob eats 10 apples +-- bob eats 5 pears +-- alice eats 4 apples +``` + + +```ts [Typescript] +import { Wildcard, pair, World } from "@rbxts/jecs" + + +const world = new World() +const Name = world.component() +function getName(e) { + return world.get(e, Name) +} + +const Eats = world.component() + +// Relationship objects +const Apples = world.component() +// components are entities, so you can add components to components +world.set(Apples, Name, "apples") +const Oranges = world.component() +world.set(Oranges, Name, "oranges") + +const bob = world.entity() +// Pairs can be constructed from two entities + +world.set(bob, pair(Eats, Apples), 10) +world.set(bob, pair(Eats, Oranges), 5) +world.set(bob, Name, "bob") + +const alice = world.entity() +world.set(alice, pair(Eats, Apples), 4) +world.set(alice, Name, "alice") + +for (const [id, amount] of world.query(pair(Eats, Wildcard))) { + // get the second target of the pair + const food = world:target(id, Eats) + print(string.format("%s eats %d %s", getName(id), amount, getName(food))) +} + +// Output: +// bob eats 10 apples +// bob eats 5 pears +// alice eats 4 apples + +``` + diff --git a/docs/overview/rbxm.png b/docs/learn/overview/rbxm.png similarity index 100% rename from docs/overview/rbxm.png rename to docs/learn/overview/rbxm.png diff --git a/docs/public/jecs_logo.svg b/docs/learn/public/jecs_logo.svg similarity index 100% rename from docs/public/jecs_logo.svg rename to docs/learn/public/jecs_logo.svg diff --git a/docs/overview/first-jecs-project.md b/docs/overview/first-jecs-project.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/overview/first-jecs-project.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/src/init.luau b/src/init.luau index 0004c6c..6446e86 100644 --- a/src/init.luau +++ b/src/init.luau @@ -136,7 +136,7 @@ local function STRIP_GENERATION(e: i53): i24 end local function ECS_PAIR(pred: i53, obj: i53): i53 - return ECS_COMBINE(ECS_ENTITY_T_LO(obj), ECS_ENTITY_T_LO(pred)) + FLAGS_ADD(--[[isPair]] true) :: i53 + return ECS_COMBINE(ECS_ENTITY_T_LO(obj), ECS_ENTITY_T_LO(pred)) + FLAGS_ADD(--[[isPair]] true) :: i53 end local ERROR_ENTITY_NOT_ALIVE = "Entity is not alive" @@ -897,8 +897,8 @@ do local function world_query_with(query, ...) local ids = { ... } - for i = #compatibleArchetypes, 1, -1 do - local archetype = compatibleArchetypes[i] + for i = #compatible_archetypes, 1, -1 do + local archetype = compatible_archetypes[i] local records = archetype.records local shouldRemove = false @@ -910,11 +910,11 @@ do end if shouldRemove then - table.remove(compatibleArchetypes, i) + table.remove(compatible_archetypes, i) end end - if #compatibleArchetypes == 0 then + if #compatible_archetypes == 0 then return EmptyQuery end @@ -928,7 +928,7 @@ do end local indices = {} - local compatibleArchetypes = {} + compatible_archetypes = {} local length = 0 local components = { ... } :: any @@ -970,11 +970,10 @@ do end length += 1 - compatibleArchetypes[length] = compatibleArchetype + compatible_archetypes[length] = compatibleArchetype indices[length] = records end - compatible_archetypes = compatibleArchetypes column_indices = indices ids = components @@ -997,6 +996,9 @@ do with = world_query_with, without = world_query_without, replace = world_query_replace, + archetypes = function() + return compatible_archetypes + end } :: any setmetatable(it, it) @@ -1189,13 +1191,11 @@ return { OnAdd = EcsOnAdd :: Entity, OnRemove = EcsOnRemove :: Entity, OnSet = EcsOnSet :: Entity, - - Wildcard = EcsWildcard :: Entity, - w = EcsWildcard :: Entity, ChildOf = EcsChildOf, Component = EcsComponent, - Rest = EcsRest, + Wildcard = EcsWildcard :: Entity, + w = EcsWildcard :: Entity, pair = (ECS_PAIR :: any) :: (pred: Entity, obj: Entity) -> number,