mirror of
https://github.com/Ukendio/jecs.git
synced 2025-04-24 17:10:03 +00:00
Marcus
GitHub
parent
4f65be279b
commit
f91ab4049f
4 changed files with 1007 additions and 962 deletions
|
|
@ -38,7 +38,8 @@ export default defineConfig({
|
|||
{ text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
|
||||
{ text: 'Queries', link: '/learn/concepts/queries' },
|
||||
{ text: 'Relationships', link: '/learn/concepts/relationships' },
|
||||
{ text: 'Builtin Component Traits', link: 'learn/concepts/builtin-component-traits' }
|
||||
{ text: 'Component Traits', link: 'learn/concepts/component-traits' },
|
||||
{ text: 'Addons', link: '/learn/addons' }
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
16
docs/learn/concepts/addons.md
Normal file
16
docs/learn/concepts/addons.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# Addons
|
||||
A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request]()!
|
||||
|
||||
# Debuggers
|
||||
|
||||
## [jabby](https://github.com/alicesaidhi/jabby)
|
||||
|
||||
A jecs debugger with a string-based query language and entity editing capabilities.
|
||||
|
||||
# Schedulers
|
||||
|
||||
## [sapphire-jecs](https://github.com/Mark-Marks/sapphire/tree/main/crates/sapphire-jecs)
|
||||
|
||||
A batteries-included [sapphire](https://github.com/mark-marks/sapphire) scheduler for jecs
|
||||
|
||||
This page takes wording and terminology directly from Bevy's [assets page](https://bevyengine.org/assets/)
|
||||
|
|
@ -1,10 +1,49 @@
|
|||
# Builtin Component Traits
|
||||
# Component Traits
|
||||
Component traits are IDs and pairs that can be added to components to modify their behavior. Although it is possible to create custom traits, this manual only contains an overview of all builtin component traits supported by Jecs.
|
||||
|
||||
Component traits are IDs and pairs that can be added to components to modify their behavior. This manual contains an overview of all component traits supported by Jecs.
|
||||
# Component
|
||||
Every (component) ID comes with a `Component` which helps with the distinction between normal entities and component IDs.
|
||||
|
||||
# Tag
|
||||
A (component) ID can be marked with `Tag´ in which the component will never contain any data. This allows for zero-cost components which improves performance for structural changes.
|
||||
|
||||
# Hooks
|
||||
Hooks are part of the "interface" of a component. You could consider hooks as the counterpart to OOP methods in ECS. They define the behavior of a component, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnSet` hook per component, just like you can only have a single constructor and destructor.
|
||||
|
||||
## Examples
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local Transform= world:component()
|
||||
world:set(Transform, OnAdd, function(entity)
|
||||
-- A transform component has been added to an entity
|
||||
end)
|
||||
world:set(Transform, OnRemove, function(entity)
|
||||
-- A transform component has been removed from the entity
|
||||
end)
|
||||
world:set(Transform, OnSet, function(entity, value)
|
||||
-- A transform component has been assigned/changed to value on the entity
|
||||
end)
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
|
||||
const Transform = world.component()
|
||||
world.set(Transform, OnAdd, (entity) => {
|
||||
// A transform component has been added to an entity
|
||||
})
|
||||
world.set(Transform, OnRemove, (entity) => {
|
||||
// A transform component has been removed from the entity
|
||||
})
|
||||
world.set(Transform, OnSet, (entity, value) => {
|
||||
// A transform component has been assigned/changed to value on the entity
|
||||
})
|
||||
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
# Cleanup Traits
|
||||
|
||||
When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
|
||||
|
||||
We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
|
||||
|
|
@ -24,11 +63,9 @@ There are two cleanup conditions:
|
|||
- `OnDeleteTarget`: a target used with the relationship is deleted
|
||||
|
||||
## Examples
|
||||
|
||||
The following examples show how to use cleanup traits
|
||||
|
||||
### (OnDelete, Remove)
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
|
|
@ -83,7 +120,6 @@ world.delete(Archer)
|
|||
:::
|
||||
|
||||
### (OnDeleteTarget, Delete)
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
|
|
@ -272,7 +272,8 @@ local function hash(arr: { number }): string
|
|||
return table.concat(arr, "_")
|
||||
end
|
||||
|
||||
local world_get: (world: World, entityId: i53, a: i53, b: i53?, c: i53?, d: i53?, e: i53?) -> (...any)
|
||||
local world_get: (world: World, entityId: i53,
|
||||
a: i53, b: i53?, c: i53?, d: i53?, e: i53?) -> ...any
|
||||
do
|
||||
-- Keeping the function as small as possible to enable inlining
|
||||
local records
|
||||
|
|
@ -289,7 +290,9 @@ do
|
|||
return columns[tr.column][row]
|
||||
end
|
||||
|
||||
function world_get(world: World, entity: i53, a: i53, b: i53?, c: i53?, d: i53?, e: i53?): ...any
|
||||
function world_get(world: World, entity: i53,
|
||||
a: i53, b: i53?, c: i53?, d: i53?, e: i53?): ...any
|
||||
|
||||
local record = world.entityIndex.sparse[entity]
|
||||
if not record then
|
||||
return nil
|
||||
|
|
@ -401,7 +404,9 @@ end
|
|||
-- TODO:
|
||||
-- should have an additional `nth` parameter which selects the nth target
|
||||
-- this is important when an entity can have multiple relationships with the same target
|
||||
local function world_target(world: World, entity: i53, relation: i24--[[, nth: number]]): i24?
|
||||
local function world_target(world: World, entity: i53,
|
||||
relation: i24--[[, nth: number]]): i24?
|
||||
|
||||
local record = world.entityIndex.sparse[entity]
|
||||
local archetype = record.archetype
|
||||
if not archetype then
|
||||
|
|
@ -421,10 +426,7 @@ local function world_target(world: World, entity: i53, relation: i24--[[, nth: n
|
|||
return ecs_pair_second(world, archetype.types[tr.column])
|
||||
end
|
||||
|
||||
local function id_record_ensure(
|
||||
world: World,
|
||||
id: number
|
||||
): ArchetypeMap
|
||||
local function id_record_ensure(world: World, id: number): ArchetypeMap
|
||||
local componentIndex = world.componentIndex
|
||||
local idr = componentIndex[id]
|
||||
|
||||
|
|
@ -433,8 +435,7 @@ local function id_record_ensure(
|
|||
local relation = ECS_ENTITY_T_HI(id)
|
||||
|
||||
local cleanup_policy = world_target(world, relation, EcsOnDelete)
|
||||
local cleanup_policy_target = world_target(world, relation,
|
||||
EcsOnDeleteTarget)
|
||||
local cleanup_policy_target = world_target(world, relation, EcsOnDeleteTarget)
|
||||
|
||||
if cleanup_policy == EcsDelete or cleanup_policy_target == EcsDelete then
|
||||
flags = bit32.bor(flags, ECS_ID_DELETE)
|
||||
|
|
@ -457,7 +458,7 @@ local function id_record_ensure(
|
|||
idr = {
|
||||
size = 0,
|
||||
cache = {},
|
||||
flags = flags
|
||||
flags = flags,
|
||||
} :: ArchetypeMap
|
||||
componentIndex[id] = idr
|
||||
end
|
||||
|
|
@ -754,16 +755,16 @@ local function world_clear(world: World, entity: i53)
|
|||
entity_move(world.entityIndex, entity, record, ROOT_ARCHETYPE)
|
||||
end
|
||||
|
||||
local function archetype_fast_delete_last(columns, column_count,
|
||||
types, entity)
|
||||
local function archetype_fast_delete_last(columns: { Column },
|
||||
column_count: number, types: { i53 }, entity: i53)
|
||||
|
||||
for i, column in columns do
|
||||
column[column_count] = nil
|
||||
end
|
||||
end
|
||||
|
||||
local function archetype_fast_delete(columns, column_count,
|
||||
row, types, entity)
|
||||
local function archetype_fast_delete(columns: { Column },
|
||||
column_count: number, row, types, entity)
|
||||
|
||||
for i, column in columns do
|
||||
column[row] = column[column_count]
|
||||
|
|
@ -771,8 +772,6 @@ local function archetype_fast_delete(columns, column_count,
|
|||
end
|
||||
end
|
||||
|
||||
local ERROR_DELETE_PANIC = "Tried to delete entity that has (OnDelete, Panic)"
|
||||
|
||||
local function archetype_delete(world: World,
|
||||
archetype: Archetype, row: number)
|
||||
|
||||
|
|
@ -802,14 +801,11 @@ local function archetype_delete(world: World,
|
|||
end
|
||||
|
||||
if row == last then
|
||||
archetype_fast_delete_last(columns,
|
||||
column_count, types, delete)
|
||||
archetype_fast_delete_last(columns, column_count, types, delete)
|
||||
else
|
||||
archetype_fast_delete(columns, column_count,
|
||||
row, types, delete)
|
||||
archetype_fast_delete(columns, column_count, row, types, delete)
|
||||
end
|
||||
|
||||
|
||||
local component_index = world.componentIndex
|
||||
local archetypes = world.archetypes
|
||||
|
||||
|
|
@ -933,8 +929,7 @@ end
|
|||
|
||||
type CompatibleArchetype = { archetype: Archetype, indices: { number } }
|
||||
|
||||
local function noop()
|
||||
end
|
||||
local function noop() end
|
||||
|
||||
local function Arm(query, ...)
|
||||
return query
|
||||
|
|
@ -1057,7 +1052,7 @@ do
|
|||
end
|
||||
|
||||
local row = i
|
||||
i-=1
|
||||
i -= 1
|
||||
|
||||
return entityId, a[row]
|
||||
end
|
||||
|
|
@ -1084,7 +1079,7 @@ do
|
|||
end
|
||||
|
||||
local row = i
|
||||
i-=1
|
||||
i -= 1
|
||||
|
||||
return entityId, a[row], b[row]
|
||||
end
|
||||
|
|
@ -1112,7 +1107,7 @@ do
|
|||
end
|
||||
|
||||
local row = i
|
||||
i-=1
|
||||
i -= 1
|
||||
|
||||
return entityId, a[row], b[row], c[row]
|
||||
end
|
||||
|
|
@ -1141,7 +1136,7 @@ do
|
|||
end
|
||||
|
||||
local row = i
|
||||
i-=1
|
||||
i -= 1
|
||||
|
||||
return entityId, a[row], b[row], c[row], d[row]
|
||||
end
|
||||
|
|
@ -1198,7 +1193,7 @@ do
|
|||
end
|
||||
|
||||
local row = i
|
||||
i-=1
|
||||
i -= 1
|
||||
|
||||
if not F then
|
||||
return entityId, a[row], b[row], c[row], d[row], e[row]
|
||||
|
|
@ -1322,7 +1317,7 @@ do
|
|||
return query
|
||||
end
|
||||
|
||||
local function world_query_replace(query, fn: (...any) -> (...any))
|
||||
local function world_query_replace(query, fn: (...any) -> ...any)
|
||||
query_init(query)
|
||||
|
||||
for i, archetype in compatible_archetypes do
|
||||
|
|
@ -1351,15 +1346,13 @@ do
|
|||
local vc = columns[records[C].column]
|
||||
local vd = columns[records[D].column]
|
||||
|
||||
va[row], vb[row], vc[row], vd[row] = fn(
|
||||
va[row], vb[row], vc[row], vd[row])
|
||||
va[row], vb[row], vc[row], vd[row] = fn(va[row], vb[row], vc[row], vd[row])
|
||||
else
|
||||
for j, id in ids do
|
||||
local tr = records[id]
|
||||
queryOutput[j] = columns[tr.column][row]
|
||||
end
|
||||
world_query_replace_values(row, columns,
|
||||
fn(unpack(queryOutput)))
|
||||
world_query_replace_values(row, columns, fn(unpack(queryOutput)))
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
@ -1430,7 +1423,7 @@ do
|
|||
with = world_query_with,
|
||||
without = world_query_without,
|
||||
replace = world_query_replace,
|
||||
archetypes = world_query_archetypes
|
||||
archetypes = world_query_archetypes,
|
||||
} :: any
|
||||
|
||||
setmetatable(it, it)
|
||||
|
|
@ -1478,8 +1471,7 @@ function World.new()
|
|||
entity_index_new_id(self.entityIndex, i)
|
||||
end
|
||||
|
||||
world_add(self, EcsChildOf,
|
||||
ECS_PAIR(EcsOnDeleteTarget, EcsDelete))
|
||||
world_add(self, EcsChildOf, ECS_PAIR(EcsOnDeleteTarget, EcsDelete))
|
||||
|
||||
return self
|
||||
end
|
||||
|
|
@ -1490,19 +1482,19 @@ export type Pair = number
|
|||
|
||||
type Item<T...> = (self: Query<T...>) -> (Entity, T...)
|
||||
|
||||
export type Entity<T = nil> = number & {__T: T }
|
||||
export type Entity<T = nil> = number & { __T: T }
|
||||
|
||||
type Iter<T...> = (query: Query<T...>) -> () -> (Entity, T...)
|
||||
|
||||
type Query<T...> = typeof(setmetatable({}, {
|
||||
__iter = (nil :: any) :: Iter<T...>
|
||||
__iter = (nil :: any) :: Iter<T...>,
|
||||
})) & {
|
||||
iter: Iter<T...>,
|
||||
next: Item<T...>,
|
||||
drain: (self: Query<T...>) -> Query<T...>,
|
||||
with: (self: Query<T...>, ...i53) -> Query<T...>,
|
||||
without: (self: Query<T...>, ...i53) -> Query<T...>,
|
||||
replace: (self: Query<T...>, <U...>(T...) -> (U...)) -> (),
|
||||
replace: (self: Query<T...>, <U...>(T...) -> U...) -> (),
|
||||
archetypes: () -> { Archetype },
|
||||
}
|
||||
|
||||
|
|
@ -1594,7 +1586,7 @@ export type World = {
|
|||
Id<H>,
|
||||
...Id<any>
|
||||
) -> Query<A, B, C, D, E, F, G, H>),
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
World = World :: { new: () -> World },
|
||||
|
|
|
|||
Loading…
Reference in a new issue