Sovereignty/jecs
1
0
Fork 0
mirror of https://github.com/Ukendio/jecs.git synced 2025-04-25 09:30:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add pages to docs

Browse source
This commit is contained in:
Ukendio 2024-05-25 03:53:35 +02:00
parent 4375150683
commit 144cd044e8
6 changed files with 711 additions and 278 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docs/api-types.md Normal file
View file

@ -0,0 +1,45 @@
# World
A World contains all ECS data
Games can have multiple worlds, although typically only one is necessary. These worlds are isolated from each other, meaning they donot share the same entities nor component IDs.
---
# Entity
An unique id.
Entities consist out of a number unique to the entity in the lower 32 bits, and a counter used to track entity liveliness in the upper 32 bits. When an id is recycled, its generation count is increased. This causes recycled ids to be very large (>4 billion), which is normal.
---
# QueryIter
A result from the `World:query` function.
Queries are used to iterate over entities that match against the set collection of components.
Calling it in a loop will allow iteration over the results.
```lua
for id, enemy, charge, model in world:query(Enemy, Charge, Model) do
-- Do something
end
```
### QueryIter.without
QueryIter.without(iter: QueryIter
...: [Entity](../api-types/Entity)): QueryIter
Create a new Query Iterator from the filter
#### Parameters
world The world.
... The collection of components to filter archetypes against.
#### Returns
The new query iterator.

189
docs/api/world.md Normal file
View file

@ -0,0 +1,189 @@
# World
### World.new
World.new(): [World](../api-types/World)
Create a new world.
#### Returns
A new world
---
### World.entity
World.entity(world: [World](../api-types/World)): [Entity](../api-types/Entity)
Creates an entity in the world.
#### Returns
A new entiity id
---
### World.target
World.target(world: [World](../api-types/World),
entity: [Entity](../api-types/Entity),
rel: [Entity](../api-types/Entity)): [Entity](../api-types/Entity)
Get the target of a relationship.
This will return a target (second element of a pair) of the entity for the specified relationship.
#### Parameters
world The world.
entity The entity.
rel The relationship between the entity and the target.
#### Returns
The first target for the relationship
---
### World.add
World.add(world: [World](../api-types/World),
entity: [Entity](../api-types/Entity),
id: [Entity](../api-types/Entity)): [Entity](../api-types/Entity)
Add a (component) id to an entity.
This operation adds a single (component) id to an entity.
If the entity already has the id, this operation will have no side effects.
#### Parameters
world The world.
entity The entity.
id The id to add.
---
### World.remove
World.remove(world: [World](../api-types/World),
entity: [Entity](../api-types/Entity),
id: [Entity](../api-types/Entity)): [Entity](../api-types/Entity)
Remove a (component) id to an entity.
This operation removes a single (component) id to an entity.
If the entity already has the id, this operation will have no side effects.
#### Parameters
world The world.
entity The entity.
id The id to add.
---
### World.get
World.get(world: [World](../api-types/World),
entity: [Entity](../api-types/Entity),
id: [Entity](../api-types/Entity)): any
Gets the component data.
#### Parameters
world The world.
entity The entity.
id The id of component to get.
#### Returns
The component data, nil if the entity does not have the componnet.
---
### World.set
World.set(world: [World](../api-types/World),
entity: [Entity](../api-types/Entity),
id: [Entity](../api-types/Entity)
data: any)
Set the value of a component.
#### Parameters
world The world.
entity The entity.
id The id of the componment set.
data The data to the component.
---
### World.query
World.query(world: [World](../api-types/World),
...: [Entity](../api-types/Entity)): [QueryIter](../api-types/QueryIter)
Create a QueryIter from the list of filters.
#### Parameters
world The world.
... The collection of components to match entities against.
#### Returns
The query iterator.
---
# Pair
### pair
pair(first: [Entity](../api-types/Entity),
second: [Entity](../api-types/Entity)): [Entity](../api-types/Entity)
Creates a composite key.
#### Parameters
first The first element.
second The second element.
#### Returns
The pair of the two elements
---
### IS_PAIR
jecs.IS_PAIR(id: [Entity](../api-types/Entity)): boolean
Creates a composite key.
#### Parameters
id The id to check.
#### Returns
If id is a pair.
---
# Constants
### OnAdd
---
### OnRemove
---
### Rest
---
### OnSet
---
### Wildcard
Matches any id, returns all matches.

5
docs/world.md Normal file
View file

@ -0,0 +1,5 @@
# World
A World contains all ECS data
Games can have multiple worlds, although typically only one is necessary. These worlds are isolated from each other.
is queryable and can be used to get entities with a specific set of components. Entities are simply ever-increasing integers.

12
lib/init.lua
View file

@ -103,14 +103,6 @@ local function ECS_IS_PAIR(e: number)
return (e % 2 ^ 4) // FLAGS_PAIR ~= 0
end
function separate(e: number)
local _typeFlags = e % 0x10
-- Revert to //= after highligting gets fixed
--
e = e // ECS_ID_FLAGS_MASK
return e // ECS_ENTITY_MASK, e % ECS_GENERATION_MASK, _typeFlags
end
-- HIGH 24 bits LOW 24 bits
local function ECS_GENERATION(e: i53)
e = e // 0x10
@ -118,7 +110,9 @@ local function ECS_GENERATION(e: i53)
end
local function ECS_GENERATION_INC(e: i53)
local id, generation, flags = separate(e)
local flags = e // 0x10
local id = flags // ECS_ENTITY_MASK
local generation = flags % ECS_GENERATION_MASK
return ECS_COMBINE(id, generation + 1) + flags
end

186
mkdocs.yml Normal file
View file

@ -0,0 +1,186 @@
site_name: Fusion
site_url: https://elttob.uk/Fusion/
repo_name: dphfox/Fusion
repo_url: https://github.com/dphfox/Fusion
extra:
version:
provider: mike
theme:
name: material
custom_dir: docs/assets/overrides
logo: assets/logo
favicon: assets/logo-dark.svg
palette:
- media: "(prefers-color-scheme: dark)"
scheme: fusiondoc-dark
toggle:
icon: octicons/sun-24
title: Switch to light theme
- media: "(prefers-color-scheme: light)"
scheme: fusiondoc-light
toggle:
icon: octicons/moon-24
title: Switch to dark theme
font:
text: Plus Jakarta Sans
code: JetBrains Mono
features:
- navigation.tabs
- navigation.top
- navigation.sections
- navigation.instant
- navigation.indexes
- search.suggest
- search.highlight
icon:
repo: octicons/mark-github-16
extra_css:
- assets/theme/fusiondoc.css
- assets/theme/colours.css
- assets/theme/code.css
- assets/theme/paragraph.css
- assets/theme/page.css
- assets/theme/admonition.css
- assets/theme/404.css
- assets/theme/api-reference.css
- assets/theme/dev-tools.css
extra_javascript:
- assets/scripts/smooth-scroll.js
nav:
- Home: index.md
- Tutorials:
- Get Started: tutorials/index.md
- Installing Fusion: tutorials/get-started/installing-fusion.md
- Developer Tools: tutorials/get-started/developer-tools.md
- Getting Help: tutorials/get-started/getting-help.md
- Fundamentals:
- Scopes: tutorials/fundamentals/scopes.md
- Values: tutorials/fundamentals/values.md
- Observers: tutorials/fundamentals/observers.md
- Computeds: tutorials/fundamentals/computeds.md
- Tables:
- ForValues: tutorials/tables/forvalues.md
- ForKeys: tutorials/tables/forkeys.md
- ForPairs: tutorials/tables/forpairs.md
- Animation:
- Tweens: tutorials/animation/tweens.md
- Springs: tutorials/animation/springs.md
- Roblox:
- Hydration: tutorials/roblox/hydration.md
- New Instances: tutorials/roblox/new-instances.md
- Parenting: tutorials/roblox/parenting.md
- Events: tutorials/roblox/events.md
- Change Events: tutorials/roblox/change-events.md
- Outputs: tutorials/roblox/outputs.md
- References: tutorials/roblox/references.md
- Best Practices:
- Components: tutorials/best-practices/components.md
- Instance Handling: tutorials/best-practices/instance-handling.md
- Callbacks: tutorials/best-practices/callbacks.md
- State: tutorials/best-practices/state.md
- Sharing Values: tutorials/best-practices/sharing-values.md
- Error Safety: tutorials/best-practices/error-safety.md
- Optimisation: tutorials/best-practices/optimisation.md
- Examples:
- Home: examples/index.md
- Cookbook:
- examples/cookbook/index.md
- Player List: examples/cookbook/player-list.md
- Animated Computed: examples/cookbook/animated-computed.md
- Fetch Data From Server: examples/cookbook/fetch-data-from-server.md
- Light & Dark Theme: examples/cookbook/light-and-dark-theme.md
- Button Component: examples/cookbook/button-component.md
- Loading Spinner: examples/cookbook/loading-spinner.md
- Drag & Drop: examples/cookbook/drag-and-drop.md
- API Reference:
- api-reference/index.md
- General:
- Errors: api-reference/general/errors.md
- Types:
- Contextual: api-reference/general/types/contextual.md
- Version: api-reference/general/types/version.md
- Members:
- Contextual: api-reference/general/members/contextual.md
- Safe: api-reference/general/members/safe.md
- version: api-reference/general/members/version.md
- Memory:
- Types:
- Scope: api-reference/memory/types/scope.md
- ScopedObject: api-reference/memory/types/scopedobject.md
- Task: api-reference/memory/types/task.md
- Members:
- deriveScope: api-reference/memory/members/derivescope.md
- doCleanup: api-reference/memory/members/docleanup.md
- scoped: api-reference/memory/members/scoped.md
- State:
- Types:
- UsedAs: api-reference/state/types/usedas.md
- Computed: api-reference/state/types/computed.md
- Dependency: api-reference/state/types/dependency.md
- Dependent: api-reference/state/types/dependent.md
- For: api-reference/state/types/for.md
- Observer: api-reference/state/types/observer.md
- StateObject: api-reference/state/types/stateobject.md
- Use: api-reference/state/types/use.md
- Value: api-reference/state/types/value.md
- Members:
- Computed: api-reference/state/members/computed.md
- ForKeys: api-reference/state/members/forkeys.md
- ForPairs: api-reference/state/members/forpairs.md
- ForValues: api-reference/state/members/forvalues.md
- Observer: api-reference/state/members/observer.md
- peek: api-reference/state/members/peek.md
- Value: api-reference/state/members/value.md
- Roblox:
- Types:
- Child: api-reference/roblox/types/child.md
- PropertyTable: api-reference/roblox/types/propertytable.md
- SpecialKey: api-reference/roblox/types/specialkey.md
- Members:
- Attribute: api-reference/roblox/members/attribute.md
- AttributeChange: api-reference/roblox/members/attributechange.md
- AttributeOut: api-reference/roblox/members/attributeout.md
- Children: api-reference/roblox/members/children.md
- Hydrate: api-reference/roblox/members/hydrate.md
- New: api-reference/roblox/members/new.md
- OnChange: api-reference/roblox/members/onchange.md
- OnEvent: api-reference/roblox/members/onevent.md
- Out: api-reference/roblox/members/out.md
- Ref: api-reference/roblox/members/ref.md
- Animation:
- Types:
- Animatable: api-reference/animation/types/animatable.md
- Spring: api-reference/animation/types/spring.md
- Tween: api-reference/animation/types/tween.md
- Members:
- Tween: api-reference/animation/members/tween.md
- Spring: api-reference/animation/members/spring.md
- Extras:
- Home: extras/index.md
- Backgrounds: extras/backgrounds.md
- Brand Guidelines: extras/brand-guidelines.md
markdown_extensions:
- admonition
- attr_list
- meta
- md_in_html
- pymdownx.superfences
- pymdownx.betterem
- pymdownx.details
- pymdownx.tabbed:
alternate_style: true
- pymdownx.inlinehilite
- toc:
permalink: true
- pymdownx.highlight:
guess_lang: false
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg

62
tests/world.lua
View file

@ -1,5 +1,5 @@
local testkit = require("../testkit")
local jecs = require("../lib/init")
local testkit = require("../testkit")
local __ = jecs.Wildcard
local ECS_ID, ECS_GENERATION = jecs.ECS_ID, jecs.ECS_GENERATION
local ECS_GENERATION_INC = jecs.ECS_GENERATION_INC
@ -23,7 +23,8 @@ end
local N = 10
TEST("world", function()
do CASE "should be iterable"
do
CASE("should be iterable")
local world = jecs.World.new()
local A = world:component()
local B = world:component()
@ -55,7 +56,8 @@ TEST("world", function()
CHECK(count == 3 + 2)
end
do CASE "should query all matching entities"
do
CASE("should query all matching entities")
local world = jecs.World.new()
local A = world:component()
local B = world:component()
@ -65,7 +67,9 @@ TEST("world", function()
local id = world:entity()
world:set(id, A, true)
if i > 5 then world:set(id, B, true) end
if i > 5 then
world:set(id, B, true)
end
entities[i] = id
end
@ -74,10 +78,10 @@ TEST("world", function()
end
CHECK(#entities == 0)
end
do CASE "should query all matching entities when irrelevant component is removed"
do
CASE("should query all matching entities when irrelevant component is removed")
local world = jecs.World.new()
local A = world:component()
local B = world:component()
@ -91,7 +95,9 @@ TEST("world", function()
-- https://github.com/Ukendio/jecs/pull/15
world:set(id, B, true)
world:set(id, A, true)
if i > 5 then world:remove(id, B) end
if i > 5 then
world:remove(id, B)
end
entities[i] = id
end
@ -104,7 +110,8 @@ TEST("world", function()
CHECK(added == N)
end
do CASE "should query all entities without B"
do
CASE("should query all entities without B")
local world = jecs.World.new()
local A = world:component()
local B = world:component()
@ -119,7 +126,6 @@ TEST("world", function()
else
world:set(id, B, true)
end
end
for id in world:query(A):without(B) do
@ -127,10 +133,10 @@ TEST("world", function()
end
CHECK(#entities == 0)
end
do CASE "should allow setting components in arbitrary order"
do
CASE("should allow setting components in arbitrary order")
local world = jecs.World.new()
local Health = world:entity()
@ -143,7 +149,8 @@ TEST("world", function()
CHECK(world:get(id, Poison) == 5)
end
do CASE "should allow deleting components"
do
CASE("should allow deleting components")
local world = jecs.World.new()
local Health = world:entity()
@ -162,10 +169,10 @@ TEST("world", function()
CHECK(world:get(id, Health) == nil)
CHECK(world:get(id1, Poison) == 500)
CHECK(world:get(id1, Health) == 50)
end
do CASE "should allow remove that doesn't exist on entity"
do
CASE("should allow remove that doesn't exist on entity")
local world = jecs.World.new()
local Health = world:entity()
@ -179,7 +186,8 @@ TEST("world", function()
CHECK(world:get(id, Health) == 50)
end
do CASE "should increment generation"
do
CASE("should increment generation")
local world = jecs.World.new()
local e = world:entity()
CHECK(ECS_ID(e) == 1 + jecs.Rest)
@ -189,7 +197,8 @@ TEST("world", function()
CHECK(ECS_GENERATION(e) == 1) -- 1
end
do CASE "should get alive from index in the dense array"
do
CASE("should get alive from index in the dense array")
local world = jecs.World.new()
local _e = world:entity()
local e2 = world:entity()
@ -203,7 +212,8 @@ TEST("world", function()
CHECK(ECS_PAIR_OBJECT(world.entityIndex, pair) == e3)
end
do CASE "should allow querying for relations"
do
CASE("should allow querying for relations")
local world = jecs.World.new()
local Eats = world:entity()
local Apples = world:entity()
@ -216,7 +226,8 @@ TEST("world", function()
end
end
do CASE "should allow wildcards in queries"
do
CASE("should allow wildcards in queries")
local world = jecs.World.new()
local Eats = world:entity()
local Apples = world:entity()
@ -235,7 +246,8 @@ TEST("world", function()
end
end
do CASE "should match against multiple pairs"
do
CASE("should match against multiple pairs")
local world = jecs.World.new()
local Eats = world:entity()
local Apples = world:entity()
@ -267,7 +279,8 @@ TEST("world", function()
CHECK(count == 1)
end
do CASE "should only relate alive entities"
do
CASE("should only relate alive entities")
local world = jecs.World.new()
local Eats = world:entity()
@ -294,7 +307,8 @@ TEST("world", function()
CHECK(world:get(bob, ECS_PAIR(Eats, Apples)) == nil)
end
do CASE "should error when setting invalid pair"
do
CASE("should error when setting invalid pair")
local world = jecs.World.new()
local Eats = world:entity()
local Apples = world:entity()
@ -302,12 +316,11 @@ TEST("world", function()
world:delete(Apples)
CHECK_NO_ERR("Apples should be dead", function()
world:set(bob, ECS_PAIR(Eats, Apples), "bob eats apples")
end)
end
do CASE "should find target for ChildOf"
do
CASE("should find target for ChildOf")
local world = jecs.World.new()
local ChildOf = world:component()
@ -337,3 +350,4 @@ TEST("world", function()
end)
FINISH()