mirror of
https://github.com/Ukendio/jecs.git
synced 2026-02-04 15:15:21 +00:00
Replace docs site with luau files
This commit is contained in:
Ukendio
parent
4123fa01ad
commit
b8c0cc0010
48 changed files with 1169 additions and 8535 deletions
425
addons/ob.luau
425
addons/ob.luau
|
|
@ -1,425 +0,0 @@
|
|||
--!strict
|
||||
local jecs = require("@jecs")
|
||||
|
||||
type World = jecs.World
|
||||
|
||||
type Id<T=any> = jecs.Id<T>
|
||||
|
||||
|
||||
export type Observer = {
|
||||
disconnect: () -> (),
|
||||
}
|
||||
|
||||
export type Monitor = {
|
||||
disconnect: () -> (),
|
||||
added: ((jecs.Entity) -> ()) -> (),
|
||||
removed: ((jecs.Entity) -> ()) -> ()
|
||||
}
|
||||
|
||||
local function observers_new(
|
||||
query: jecs.Query<...any>,
|
||||
callback: (jecs.Entity) -> ()
|
||||
): Observer
|
||||
local cachedquery = query:cached()
|
||||
|
||||
local world = (cachedquery :: jecs.Query<any> & { world: World }).world
|
||||
callback = callback
|
||||
|
||||
local archetypes = cachedquery.archetypes_map
|
||||
local terms = query.filter_with :: { jecs.Id<any> }
|
||||
|
||||
local entity_index = world.entity_index
|
||||
|
||||
local function emplaced<a>(
|
||||
entity: jecs.Entity,
|
||||
id: jecs.Id<a>,
|
||||
value: a,
|
||||
oldarchetype: jecs.Archetype
|
||||
)
|
||||
local r = entity_index.sparse_array[jecs.ECS_ID(entity)]
|
||||
|
||||
local archetype = r.archetype
|
||||
|
||||
if archetypes[archetype.id] then
|
||||
callback(entity)
|
||||
end
|
||||
end
|
||||
|
||||
local cleanup = {}
|
||||
|
||||
for _, term in terms do
|
||||
if jecs.IS_PAIR(term) then
|
||||
local rel = jecs.ECS_PAIR_FIRST(term)
|
||||
local tgt = jecs.ECS_PAIR_SECOND(term)
|
||||
local wc = tgt == jecs.w
|
||||
|
||||
local function emplaced_w_pair(entity, id, value, oldarchetype: jecs.Archetype)
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
local r = jecs.record(world, entity)
|
||||
if archetypes[r.archetype.id] then
|
||||
callback(entity)
|
||||
end
|
||||
end
|
||||
|
||||
local onadded = world:added(rel, emplaced_w_pair)
|
||||
local onchanged = world:changed(rel, emplaced_w_pair)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onchanged)
|
||||
else
|
||||
local onadded = world:added(term, emplaced)
|
||||
local onchanged = world:changed(term, emplaced)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onchanged)
|
||||
end
|
||||
end
|
||||
|
||||
local without = query.filter_without
|
||||
if without then
|
||||
for _, term in without do
|
||||
if jecs.IS_PAIR(term) then
|
||||
local rel = jecs.ECS_PAIR_FIRST(term)
|
||||
local tgt = jecs.ECS_PAIR_SECOND(term)
|
||||
local wc = tgt == jecs.w
|
||||
local onremoved = world:removed(rel, function(entity, id, delete: boolean?)
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if archetype then
|
||||
local dst = jecs.archetype_traverse_remove(world, id, archetype)
|
||||
if archetypes[dst.id] then
|
||||
callback(entity)
|
||||
end
|
||||
end
|
||||
end)
|
||||
|
||||
table.insert(cleanup, onremoved)
|
||||
else
|
||||
local onremoved = world:removed(term, function(entity, id)
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if archetype then
|
||||
local dst = jecs.archetype_traverse_remove(world, id, archetype)
|
||||
if archetypes[dst.id] then
|
||||
callback(entity)
|
||||
end
|
||||
end
|
||||
end)
|
||||
|
||||
table.insert(cleanup, onremoved)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
local function disconnect()
|
||||
for _, disconnect in cleanup do
|
||||
disconnect()
|
||||
end
|
||||
end
|
||||
|
||||
local observer = {
|
||||
disconnect = disconnect,
|
||||
}
|
||||
|
||||
return observer
|
||||
end
|
||||
|
||||
local function monitors_new(query: jecs.Query<...any>): Monitor
|
||||
local cachedquery = query:cached()
|
||||
|
||||
local world = (cachedquery :: jecs.Query<...any> & { world: World }).world :: jecs.World
|
||||
|
||||
local archetypes = cachedquery.archetypes_map
|
||||
local terms = cachedquery.filter_with :: { jecs.Id<any> }
|
||||
|
||||
local entity_index = world.entity_index :: any
|
||||
|
||||
local terms_lookup: { [jecs.Id<any>]: boolean } = {}
|
||||
for _, term in terms do
|
||||
terms_lookup[term] = true
|
||||
end
|
||||
|
||||
local callback_added: ((jecs.Entity) -> ())?
|
||||
local callback_removed: ((jecs.Entity) -> ())?
|
||||
|
||||
-- NOTE(marcus): Track the last (entity, old archetype) pair we processed to detect bulk operations.
|
||||
-- During bulk_insert from ROOT_ARCHETYPE, the entity is moved to the target archetype first,
|
||||
-- then all on_add callbacks fire sequentially with the same oldarchetype for the same entity.
|
||||
-- We track both entity and old archetype to distinguish between:
|
||||
-- 1. Same entity, same old archetype (bulk operation - skip)
|
||||
-- 2. Different entity, same old archetype (separate operation - don't skip)
|
||||
local last_old_archetype: jecs.Archetype? = nil
|
||||
local last_entity: jecs.Entity? = nil
|
||||
|
||||
local function emplaced<a>(
|
||||
entity: jecs.Entity,
|
||||
id: jecs.Id<a>,
|
||||
value: a,
|
||||
oldarchetype: jecs.Archetype
|
||||
)
|
||||
if callback_added == nil then
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.entity_index_try_get_fast(
|
||||
entity_index, entity :: any) :: jecs.Record
|
||||
if not archetypes[oldarchetype.id] and archetypes[r.archetype.id] then
|
||||
-- NOTE(marcus): Skip if we've seen this exact (entity, old archetype) combination before
|
||||
-- AND this component is in the query's terms. This detects bulk operations where
|
||||
-- the same entity transitions with multiple components, while allowing different
|
||||
-- entities to trigger even if they share the same old archetype.
|
||||
if last_old_archetype == oldarchetype and last_entity == entity and terms_lookup[id] then
|
||||
return
|
||||
end
|
||||
|
||||
last_old_archetype = oldarchetype
|
||||
last_entity = entity
|
||||
callback_added(entity)
|
||||
else
|
||||
-- NOTE(marcus): Clear tracking when we see a different transition pattern
|
||||
last_old_archetype = nil
|
||||
last_entity = nil
|
||||
end
|
||||
end
|
||||
|
||||
-- Track which entity we've already processed for deletion to avoid duplicate callbacks
|
||||
-- during bulk deletion where multiple components are removed with delete=true
|
||||
local last_deleted_entity: jecs.Entity? = nil
|
||||
|
||||
local function removed(entity: jecs.Entity, component: jecs.Component, delete:boolean?)
|
||||
if callback_removed == nil then
|
||||
return
|
||||
end
|
||||
|
||||
if delete then
|
||||
-- Deletion is a bulk removal - all components are removed with delete=true
|
||||
-- We should only trigger the callback once per entity, not once per component
|
||||
if last_deleted_entity == entity then
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.record(world, entity)
|
||||
if r and r.archetype and archetypes[r.archetype.id] then
|
||||
-- Entity was in the monitor before deletion
|
||||
last_deleted_entity = entity
|
||||
-- Clear tracking when entity is deleted
|
||||
last_old_archetype = nil
|
||||
last_entity = nil
|
||||
callback_removed(entity)
|
||||
end
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.record(world, entity)
|
||||
local src = r.archetype
|
||||
|
||||
local dst = jecs.archetype_traverse_remove(world, component, src)
|
||||
|
||||
if not archetypes[dst.id] then
|
||||
-- Clear tracking when entity leaves the monitor to allow re-entry
|
||||
last_old_archetype = nil
|
||||
last_entity = nil
|
||||
last_deleted_entity = nil
|
||||
callback_removed(entity)
|
||||
end
|
||||
end
|
||||
|
||||
local cleanup = {}
|
||||
|
||||
for _, term in terms do
|
||||
if jecs.IS_PAIR(term) then
|
||||
local rel = jecs.ECS_PAIR_FIRST(term)
|
||||
local tgt = jecs.ECS_PAIR_SECOND(term)
|
||||
local wc = tgt == jecs.w
|
||||
|
||||
local onadded = world:added(rel, function(entity, id, _, oldarchetype: jecs.Archetype)
|
||||
if callback_added == nil then
|
||||
return
|
||||
end
|
||||
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.entity_index_try_get_fast(
|
||||
entity_index, entity :: any) :: jecs.Record
|
||||
|
||||
if not archetypes[oldarchetype.id] and archetypes[r.archetype.id] then
|
||||
-- NOTE(marcus): Skip if we've seen this exact (entity, old archetype) combination before
|
||||
-- AND this component is in the query's terms.
|
||||
if last_old_archetype == oldarchetype and last_entity == entity and terms_lookup[id] then
|
||||
return
|
||||
end
|
||||
|
||||
last_old_archetype = oldarchetype
|
||||
last_entity = entity
|
||||
callback_added(entity)
|
||||
else
|
||||
-- Clear tracking when we see a different transition pattern
|
||||
last_old_archetype = nil
|
||||
last_entity = nil
|
||||
end
|
||||
end)
|
||||
local onremoved = world:removed(rel, function(entity, id, deleted)
|
||||
if callback_removed == nil then
|
||||
return
|
||||
end
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.record(world, entity)
|
||||
if archetypes[r.archetype.id] then
|
||||
last_old_archetype = nil
|
||||
callback_removed(entity)
|
||||
end
|
||||
end)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onremoved)
|
||||
else
|
||||
local onadded = world:added(term, emplaced)
|
||||
local onremoved = world:removed(term, removed)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onremoved)
|
||||
end
|
||||
|
||||
end
|
||||
|
||||
local without = query.filter_without
|
||||
if without then
|
||||
for _, term in without do
|
||||
if jecs.IS_PAIR(term) then
|
||||
local rel = jecs.ECS_PAIR_FIRST(term)
|
||||
local tgt = jecs.ECS_PAIR_SECOND(term)
|
||||
local wc = tgt == jecs.w
|
||||
local onadded = world:added(rel, function(entity, id, _, oldarchetype: jecs.Archetype)
|
||||
if callback_removed == nil then
|
||||
return
|
||||
end
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if not archetype then
|
||||
return
|
||||
end
|
||||
|
||||
-- NOTE(marcus): This check that it was presently in
|
||||
-- the query but distinctively leaves is important as
|
||||
-- sometimes it could be too eager to report that it
|
||||
-- removed a component even though the entity is not
|
||||
-- apart of the monitor
|
||||
if archetypes[oldarchetype.id] and not archetypes[archetype.id] then
|
||||
last_old_archetype = nil
|
||||
callback_removed(entity)
|
||||
end
|
||||
end)
|
||||
local onremoved = world:removed(rel, function(entity, id, delete)
|
||||
if delete then
|
||||
return
|
||||
end
|
||||
if callback_added == nil then
|
||||
return
|
||||
end
|
||||
if not wc and id ~= term then
|
||||
return
|
||||
end
|
||||
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if not archetype then
|
||||
return
|
||||
end
|
||||
if last_old_archetype == archetype and terms_lookup[id] then
|
||||
return
|
||||
end
|
||||
|
||||
local dst = jecs.archetype_traverse_remove(world, id, archetype)
|
||||
|
||||
if archetypes[dst.id] then
|
||||
last_old_archetype = archetype
|
||||
callback_added(entity)
|
||||
end
|
||||
end)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onremoved)
|
||||
else
|
||||
local onadded = world:added(term, function(entity, id, _, oldarchetype: jecs.Archetype)
|
||||
if callback_removed == nil then
|
||||
return
|
||||
end
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if not archetype then
|
||||
return
|
||||
end
|
||||
|
||||
-- NOTE(marcus): Sometimes OnAdd listeners for excluded
|
||||
-- terms are too eager to report that it is leaving the
|
||||
-- monitor even though the entity is not apart of it
|
||||
-- already.
|
||||
if archetypes[oldarchetype.id] and not archetypes[archetype.id] then
|
||||
callback_removed(entity)
|
||||
end
|
||||
end)
|
||||
local onremoved = world:removed(term, function(entity, id, delete)
|
||||
if delete then
|
||||
return
|
||||
end
|
||||
if callback_added == nil then
|
||||
return
|
||||
end
|
||||
local r = jecs.record(world, entity)
|
||||
local archetype = r.archetype
|
||||
if not archetype then
|
||||
return
|
||||
end
|
||||
local dst = jecs.archetype_traverse_remove(world, id, archetype)
|
||||
|
||||
-- NOTE(marcus): Inversely with the opposite operation, you
|
||||
-- only need to check if it is going to enter the query once
|
||||
-- because world:remove already stipulates that it is
|
||||
-- idempotent so that this hook won't be invoked if it is
|
||||
-- was already removed.
|
||||
if archetypes[dst.id] then
|
||||
callback_added(entity)
|
||||
end
|
||||
end)
|
||||
table.insert(cleanup, onadded)
|
||||
table.insert(cleanup, onremoved)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
local function disconnect()
|
||||
for _, disconnect in cleanup do
|
||||
disconnect()
|
||||
end
|
||||
end
|
||||
|
||||
local function monitor_added(callback)
|
||||
callback_added = callback
|
||||
end
|
||||
|
||||
local function monitor_removed(callback)
|
||||
callback_removed = callback
|
||||
end
|
||||
|
||||
local monitor = {
|
||||
disconnect = disconnect,
|
||||
added = monitor_added,
|
||||
removed = monitor_removed
|
||||
} :: Monitor
|
||||
|
||||
return monitor
|
||||
end
|
||||
|
||||
return {
|
||||
monitor = monitors_new,
|
||||
observer = observers_new,
|
||||
test = function(q: jecs.Query<...any>) end
|
||||
}
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
import { defineConfig } from "vitepress";
|
||||
|
||||
// https://vitepress.dev/reference/site-config
|
||||
export default defineConfig({
|
||||
title: "Jecs",
|
||||
base: "/jecs/",
|
||||
description: "A VitePress Site",
|
||||
themeConfig: {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
nav: [
|
||||
{ text: "Learn", link: "/learn/overview.md" },
|
||||
{ text: "API", link: "/api/jecs.md" },
|
||||
{ text: "Resources", link: "/resources" },
|
||||
],
|
||||
|
||||
sidebar: {
|
||||
"/api/": [
|
||||
{
|
||||
text: "Namespaces",
|
||||
items: [
|
||||
{ text: "jecs", link: "/api/jecs" },
|
||||
{ text: "World", link: "/api/world" },
|
||||
{ text: "Query", link: "/api/query" },
|
||||
],
|
||||
},
|
||||
],
|
||||
"/learn/": [
|
||||
{
|
||||
text: "API Reference",
|
||||
items: [
|
||||
{ text: "jecs", link: "/api/jecs" },
|
||||
{ text: "World", link: "/api/world" },
|
||||
{ text: "Query", link: "/api/query" },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: "Contributing",
|
||||
items: [
|
||||
{ text: "Contribution Guidelines", link: "/learn/contributing/guidelines" },
|
||||
{ text: "Submitting Issues", link: "/learn/contributing/issues" },
|
||||
{ text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" },
|
||||
{ text: "Code Coverage", link: "/learn/contributing/coverage" },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
socialLinks: [{ icon: "github", link: "https://github.com/ukendio/jecs" }],
|
||||
},
|
||||
});
|
||||
143
docs/api/jecs.md
143
docs/api/jecs.md
|
|
@ -1,143 +0,0 @@
|
|||
# Jecs
|
||||
|
||||
Jecs. Just an Entity Component System.
|
||||
|
||||
# Members
|
||||
|
||||
## World
|
||||
```luau
|
||||
jecs.World: World
|
||||
```
|
||||
A world is a container of all ECS data. Games can have multiple worlds but component IDs may conflict between worlds. Ensure to register the same component IDs in the same order for each world.
|
||||
|
||||
## Wildcard
|
||||
```luau
|
||||
jecs.Wildcard: Id
|
||||
```
|
||||
Builtin component type. This ID is used for wildcard queries.
|
||||
|
||||
## Component
|
||||
```luau
|
||||
jecs.Component: Id
|
||||
```
|
||||
Builtin component type. Every ID created with [world:component()](world.md#component()) has this type added to it. This is meant for querying every component ID.
|
||||
|
||||
## ChildOf
|
||||
```luau
|
||||
jecs.ChildOf: Id
|
||||
```
|
||||
Builtin component type. This ID is for creating parent-child hierarchies.
|
||||
|
||||
## OnAdd
|
||||
|
||||
```luau
|
||||
jecs.OnAdd: Id
|
||||
```
|
||||
Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is added.
|
||||
|
||||
## OnRemove
|
||||
|
||||
```luau
|
||||
jecs.OnRemove: Id
|
||||
```
|
||||
|
||||
Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is removed.
|
||||
|
||||
## OnChange
|
||||
|
||||
```luau
|
||||
jecs.OnChange: Id
|
||||
```
|
||||
|
||||
Builtin component type. This ID is for setting up a callback that is invoked when an instance of a component is changed.
|
||||
|
||||
## Exclusive
|
||||
|
||||
```lua
|
||||
jecs.Exclusive: Id
|
||||
```
|
||||
|
||||
Builtin component type. This ID is for encoding that an ID is Exclusive meaning that an entity can never have more than one target for that exclusive relation.
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
local ChildOf = world:entity()
|
||||
world:add(ChildOf, jecs.Exclusive)
|
||||
|
||||
local pop = world:entity()
|
||||
local dad = world:entity()
|
||||
local kid = world:entity()
|
||||
|
||||
world:add(kid, pair(ChildOf, dad))
|
||||
print(world:target(kid, ChildOf, 0) == dad)
|
||||
world:add(kid, pair(ChildOf, pop))
|
||||
print(world:target(kid, ChildOf, 1) == dad) -- If ChildOf was not exclusive this would have been true
|
||||
print(world:target(kid, ChildOf, 0) == pop)
|
||||
|
||||
-- Output:
|
||||
-- true
|
||||
-- false
|
||||
-- true
|
||||
```
|
||||
|
||||
:::info
|
||||
By default, jecs.ChildOf is already an exclusive relationship and this is just a demonstration of how to use it.
|
||||
In some cases you can use Exclusive relationships as a performance optimization as you can guarantee there will only be one target, therefore
|
||||
retrieving the data from a wildcard pair with that exclusive relationship can be deterministic.
|
||||
:::
|
||||
|
||||
## Name
|
||||
```luau
|
||||
jecs.Name: Id
|
||||
```
|
||||
Builtin component type. This ID is for naming components, but realistically you could use any component to do that.
|
||||
|
||||
## Rest
|
||||
```luau
|
||||
jecs.Rest: Id
|
||||
```
|
||||
|
||||
Builtin component type. This ID is simply for denoting the end of the range for builtin component IDs.
|
||||
|
||||
# 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
|
||||
|
||||
While relationship pairs can be used as components and have data associated with an ID, they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
|
||||
|
||||
:::
|
||||
|
||||
## pair_first()
|
||||
```luau
|
||||
function jecs.pair_first(
|
||||
pair: Id, -- A full pair ID encoded using a relation-target pair.
|
||||
): Entity -- The ID of the first element. Returns 0 if the ID is not alive.
|
||||
```
|
||||
Returns the first element (the relation part) of a pair ID.
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Likes = world:component()
|
||||
local alice = world:entity()
|
||||
local bob = world:entity()
|
||||
|
||||
local pair_id = pair(Likes, alice)
|
||||
local relation = jecs.pair_first(pair_id)
|
||||
print(relation == Likes) -- true
|
||||
```
|
||||
|
||||
## pair_second()
|
||||
```luau
|
||||
function jecs.pair_second(
|
||||
pair: Id, -- A full pair ID encoded using a relation-target pair.
|
||||
): Entity -- The ID of the second element. Returns 0 if the ID is not alive.
|
||||
```
|
||||
Returns the second element (the target part) of a pair ID.
|
||||
|
|
@ -1,196 +0,0 @@
|
|||
# Observers
|
||||
|
||||
The observers addon extends the World with signal-based reactivity and query-based observers. This addon provides a more ergonomic way to handle component lifecycle events and query changes.
|
||||
|
||||
## Installation
|
||||
|
||||
The observers addon is included with jecs and can be imported directly:
|
||||
|
||||
```luau
|
||||
local jecs = require(path/to/jecs)
|
||||
local observers_add = require(path/to/jecs/addons/observers)
|
||||
|
||||
local world = observers_add(jecs.world())
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### added
|
||||
|
||||
Registers a callback that is invoked when a component is added to any entity.
|
||||
|
||||
```luau
|
||||
function World:added<T>(
|
||||
component: Id<T>,
|
||||
callback: (entity: Entity, id: Id<T>, value: T?) -> ()
|
||||
): () -> () -- Returns an unsubscribe function
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `component` - The component ID to listen for additions
|
||||
- `callback` - Function called when component is added, receives entity, component ID, and value
|
||||
|
||||
**Returns:** An unsubscribe function that removes the listener when called
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local unsubscribe = world:added(Health, function(entity, id, value)
|
||||
print("Health component added to entity", entity, "with value", value)
|
||||
end)
|
||||
|
||||
-- Later, to stop listening:
|
||||
unsubscribe()
|
||||
```
|
||||
|
||||
### removed
|
||||
|
||||
Registers a callback that is invoked when a component is removed from any entity.
|
||||
|
||||
```luau
|
||||
function World:removed<T>(
|
||||
component: Id<T>,
|
||||
callback: (entity: Entity, id: Id<T>) -> ()
|
||||
): () -> () -- Returns an unsubscribe function
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `component` - The component ID to listen for removals
|
||||
- `callback` - Function called when component is removed, receives entity and component ID
|
||||
|
||||
**Returns:** An unsubscribe function that removes the listener when called
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local unsubscribe = world:removed(Health, function(entity, id)
|
||||
print("Health component removed from entity", entity)
|
||||
end)
|
||||
```
|
||||
|
||||
### changed
|
||||
|
||||
Registers a callback that is invoked when a component's value is changed on any entity.
|
||||
|
||||
```luau
|
||||
function World:changed<T>(
|
||||
component: Id<T>,
|
||||
callback: (entity: Entity, id: Id<T>, value: T) -> ()
|
||||
): () -> () -- Returns an unsubscribe function
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `component` - The component ID to listen for changes
|
||||
- `callback` - Function called when component value changes, receives entity, component ID, and new value
|
||||
|
||||
**Returns:** An unsubscribe function that removes the listener when called
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local unsubscribe = world:changed(Health, function(entity, id, value)
|
||||
print("Health changed to", value, "for entity", entity)
|
||||
end)
|
||||
```
|
||||
|
||||
### observer
|
||||
|
||||
Creates a query-based observer that triggers when entities match or stop matching a query.
|
||||
|
||||
```luau
|
||||
function World:observer<T...>(
|
||||
query: Query<T...>,
|
||||
callback: ((entity: Entity, id: Id, value: any?) -> ())?
|
||||
): () -> () -> Entity -- Returns an iterator function
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `query` - The query to observe for changes
|
||||
- `callback` - Optional function called when entities match the query
|
||||
|
||||
**Returns:** An iterator function that returns entities that matched the query since last iteration
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Position = world:component() :: jecs.Id<Vector3>
|
||||
local Velocity = world:component() :: jecs.Id<Vector3>
|
||||
|
||||
local moving_entities = world:observer(
|
||||
world:query(Position, Velocity),
|
||||
function(entity, id, value)
|
||||
print("Entity", entity, "started moving")
|
||||
end
|
||||
)
|
||||
|
||||
-- In your game loop:
|
||||
for entity in moving_entities() do
|
||||
-- Process newly moving entities
|
||||
end
|
||||
```
|
||||
|
||||
### monitor
|
||||
|
||||
Creates a query-based monitor that triggers when entities are added to or removed from a query.
|
||||
|
||||
```luau
|
||||
function World:monitor<T...>(
|
||||
query: Query<T...>,
|
||||
callback: ((entity: Entity, id: Id, value: any?) -> ())?
|
||||
): () -> () -> Entity -- Returns an iterator function
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `query` - The query to monitor for additions/removals
|
||||
- `callback` - Optional function called when entities are added or removed from the query
|
||||
|
||||
**Returns:** An iterator function that returns entities that were added or removed since last iteration
|
||||
|
||||
**Example:**
|
||||
```luau
|
||||
local Health = world:component() :: jecs.Id<number>
|
||||
|
||||
local health_changes = world:monitor(
|
||||
world:query(Health),
|
||||
function(entity, id, value)
|
||||
print("Health component changed for entity", entity)
|
||||
end
|
||||
)
|
||||
|
||||
-- In your game loop:
|
||||
for entity in health_changes() do
|
||||
-- Process entities with health changes
|
||||
end
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Component Lifecycle Tracking
|
||||
|
||||
```luau
|
||||
local Player = world:component()
|
||||
local Health = world:component() :: jecs.Id<number>
|
||||
|
||||
-- Track when players are created
|
||||
world:added(Player, function(entity, id, instance)
|
||||
instance:SetAttribute("entityid", entity)
|
||||
end)
|
||||
|
||||
world:removed(Player, function(entity, id)
|
||||
world:add(entity, Destroy) -- process its deletion later!
|
||||
end)
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Signal listeners** are called immediately when components are added/removed/changed
|
||||
- **Query observers** cache the query for better performance
|
||||
- **Multiple listeners** for the same component are supported and called in registration order
|
||||
- **Unsubscribe functions** should be called when listeners are no longer needed to prevent memory leaks
|
||||
- **Observer iterators** should be called regularly to clear the internal buffer
|
||||
|
||||
## Integration with Built-in Hooks
|
||||
|
||||
The observers addon integrates with the built-in component hooks (`OnAdd`, `OnRemove`, `OnChange`). If a component already has these hooks configured, the observers addon will preserve them and call both the original hook and any registered signal listeners.
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
# 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.
|
||||
|
||||
# Methods
|
||||
|
||||
## cached
|
||||
|
||||
Returns a cached version of the query. This is useful if you want to create a query that you can iterate multiple times.
|
||||
|
||||
```luau
|
||||
function Query:cached(): Query -- Returns the cached Query
|
||||
```
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local lerps = world:query(Lerp):cached() -- Ensure that you cache this outside a system so you do not create a new cache for a query every frame
|
||||
|
||||
local function system(dt)
|
||||
for entity, lerp in lerps do
|
||||
-- Do something
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const lerps = world.query(Lerp).cached()
|
||||
|
||||
function system(dt) {
|
||||
for (const [entity, lerp] of lerps) {
|
||||
// Do something
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## with
|
||||
|
||||
Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
|
||||
|
||||
```luau
|
||||
function Query:with(
|
||||
...: Entity -- The IDs to query with
|
||||
): Query
|
||||
```
|
||||
|
||||
Example:
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
for id, position in world:query(Position):with(Velocity) do
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
for (const [id, position] of world.query(Position).with(Velocity)) {
|
||||
// Do something
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
Put the IDs inside of `world:query()` instead if you need the data.
|
||||
:::
|
||||
|
||||
## without
|
||||
|
||||
Removes entities with the provided components from the query.
|
||||
|
||||
```luau
|
||||
function Query:without(
|
||||
...: Entity -- The IDs to filter against.
|
||||
): Query -- Returns the Query
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
for entity, position in world:query(Position):without(Velocity) do
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
for (const [entity, position] of world.query(Position).without(Velocity)) {
|
||||
// Do something
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## archetypes
|
||||
|
||||
Returns the matching archetypes of the query.
|
||||
|
||||
```luau
|
||||
function Query:archetypes(): { Archetype }
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```luau [luau]
|
||||
for i, archetype in world:query(Position, Velocity):archetypes() do
|
||||
local field = archetype.columns_map
|
||||
local positions = field[Position]
|
||||
local velocities = field[Velocity]
|
||||
|
||||
for row, entity in archetype.entities do
|
||||
local position = positions[row]
|
||||
local velocity = velocities[row]
|
||||
-- Do something
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
:::info
|
||||
This function is meant for people who want to really customize their query behaviour at the archetype-level
|
||||
:::
|
||||
|
||||
## iter
|
||||
In most cases, you can iterate over queries directly using `for entity, ... in query do`. The `:iter()` method is mainly useful if you are on the old solver, to get types for the returned values.
|
||||
|
||||
```luau
|
||||
function Query:iter(): () -> (Entity, ...)
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local query = world:query(Position, Velocity)
|
||||
|
||||
-- Direct iteration (recommended)
|
||||
for entity, position, velocity in query do
|
||||
-- Process entity
|
||||
end
|
||||
|
||||
-- Using explicit iterator (when needed for the old solver)
|
||||
local iterator = query:iter()
|
||||
for entity, position, velocity in iterator do
|
||||
-- Process entity
|
||||
end
|
||||
```
|
||||
|
|
@ -1,643 +0,0 @@
|
|||
# World
|
||||
|
||||
A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components and to perform different kinds of operations on them.
|
||||
|
||||
# Functions
|
||||
|
||||
## new
|
||||
|
||||
`World` utilizes a class, meaning jecs allows you to create multiple worlds.
|
||||
|
||||
```luau
|
||||
function World.new(): World
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local world = jecs.World.new()
|
||||
local myOtherWorld = jecs.World.new()
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
import { World } from "@rbxts/jecs";
|
||||
|
||||
const world = new World();
|
||||
const myOtherWorld = new World();
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
# Methods
|
||||
|
||||
## entity
|
||||
|
||||
Creates a new entity. It accepts the overload to create an entity with a specific ID.
|
||||
|
||||
```luau
|
||||
function World:entity<T>(
|
||||
id: Entity<T>? -- The desired id
|
||||
): Entity<T>
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local entity = world:entity()
|
||||
```
|
||||
```ts [typescript]
|
||||
const entity = world.entity();
|
||||
```
|
||||
:::
|
||||
|
||||
## component
|
||||
|
||||
Creates a new component. Do note components are entities as well, meaning jecs allows you to add other components onto them.
|
||||
|
||||
These are meant to be added onto other entities through `add` and `set`
|
||||
|
||||
```luau
|
||||
function World:component<T>(): Entity<T> -- The new component.
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const Health = world.component<number>();
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## get
|
||||
|
||||
Returns the data present in the component that was set in the entity. Will return nil if the component was a tag or is not present.
|
||||
|
||||
```luau
|
||||
function World:get<T>(
|
||||
entity: Entity, -- The entity
|
||||
id: Entity<T> -- The component ID to fetch
|
||||
): T?
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local Entity = world:entity()
|
||||
world:set(Entity, Health, 100)
|
||||
|
||||
print(world:get(Entity, Health))
|
||||
|
||||
-- Outputs:
|
||||
-- 100
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const Health = world.component<number>();
|
||||
|
||||
const Entity = world.entity();
|
||||
world.set(Entity, Health, 100);
|
||||
|
||||
print(world.get(Entity, Health));
|
||||
|
||||
// Outputs:
|
||||
// 100
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## has
|
||||
|
||||
Returns whether an entity has a component (ID). Useful for checking if an entity has a tag or if you don't care of the data that is inside the component.
|
||||
|
||||
```luau
|
||||
function World:has(
|
||||
entity: Entity, -- The entity
|
||||
id: Entity<T> -- The component ID to check
|
||||
): boolean
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local IsMoving = world:component()
|
||||
local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local Entity = world:entity()
|
||||
world:set(Entity, Health, 100)
|
||||
world:add(Entity, Ragdolled)
|
||||
|
||||
print(world:has(Entity, Health))
|
||||
print(world:has(Entity, IsMoving)
|
||||
|
||||
print(world:get(Entity, Ragdolled))
|
||||
print(world:has(Entity, Ragdolled))
|
||||
|
||||
-- Outputs:
|
||||
-- true
|
||||
-- false
|
||||
-- nil
|
||||
-- true
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const IsMoving = world.component();
|
||||
const Ragdolled = world.entity(); // This is a tag, meaning it won't contain data
|
||||
const Health = world.component<number>();
|
||||
|
||||
const Entity = world.entity();
|
||||
world.set(Entity, Health, 100);
|
||||
world.add(Entity, Ragdolled);
|
||||
|
||||
print(world.has(Entity, Health));
|
||||
print(world.has(Entity, IsMoving));
|
||||
|
||||
print(world.get(Entity, Ragdolled));
|
||||
print(world.has(Entity, Ragdolled));
|
||||
|
||||
// Outputs:
|
||||
// true
|
||||
// false
|
||||
// nil
|
||||
// true
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## add
|
||||
|
||||
Adds a component (ID) to the entity. Useful for adding a tag to an entity, as this adds the component to the entity without any additional values inside
|
||||
|
||||
```luau
|
||||
function World:add(
|
||||
entity: Entity, -- The entity
|
||||
id: Entity<T> -- The component ID to add
|
||||
): void
|
||||
```
|
||||
|
||||
::: info
|
||||
This function is idempotent, meaning if the entity already has the id, this operation will have no side effects.
|
||||
:::
|
||||
|
||||
## set
|
||||
|
||||
Adds or changes data in the entity's component.
|
||||
|
||||
```luau
|
||||
function World:set(
|
||||
entity: Entity, -- The entity
|
||||
id: Entity<T>, -- The component ID to set
|
||||
data: T -- The data of the component's type
|
||||
): void
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local Health = world:component() :: jecs.Entity<number>
|
||||
|
||||
local Entity = world:entity()
|
||||
world:set(Entity, Health, 100)
|
||||
|
||||
print(world:get(Entity, Health))
|
||||
|
||||
world:set(Entity, Health, 50)
|
||||
print(world:get(Entity, Health))
|
||||
|
||||
-- Outputs:
|
||||
-- 100
|
||||
-- 50
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const Health = world.component<number>();
|
||||
|
||||
const Entity = world.entity();
|
||||
world.set(Entity, Health, 100);
|
||||
|
||||
print(world.get(Entity, Health));
|
||||
|
||||
world.set(Entity, Health, 50);
|
||||
print(world.get(Entity, Health));
|
||||
|
||||
// Outputs:
|
||||
// 100
|
||||
// 50
|
||||
```
|
||||
:::
|
||||
|
||||
:::info
|
||||
`world:set(entity, component, value)` propagates that a change has happened for thes component on this entity, while mutating a value directly would not.
|
||||
:::
|
||||
|
||||
## query
|
||||
|
||||
Creates a [`query`](query) with the given components (IDs). Entities that satisfies the conditions of the query will be returned and their corresponding data.
|
||||
|
||||
```luau
|
||||
function World:query(
|
||||
...: Entity -- The components to query with
|
||||
): Query
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
-- Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
|
||||
for entity, position, velocity in world:query(Position, Velocity) do
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
// Roblox-TS allows to deconstruct tuples on the act like if they were arrays!
|
||||
// Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
|
||||
for (const [entity, position, velocity] of world.query(Position, Velocity) {
|
||||
// Do something
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
:::info
|
||||
Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
|
||||
|
||||
:::
|
||||
|
||||
## target
|
||||
|
||||
Get the target of a relationship.
|
||||
This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
|
||||
If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
|
||||
|
||||
```luau
|
||||
function World:target(
|
||||
entity: Entity, -- The entity
|
||||
relation: Id, -- The relationship between the entity and the target
|
||||
nth: number, -- The index
|
||||
): Id? -- The target for the relationship at the specified index.
|
||||
```
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local function timers_count(world: types.World)
|
||||
local timers = world
|
||||
:query(jecs.pair(ct.Timer, jecs.w))
|
||||
:without(ct.Destroy)
|
||||
:cached()
|
||||
|
||||
return function(_, dt: number)
|
||||
for entity in timers do
|
||||
local index = 0
|
||||
local nth = world:target(entity, ct.Timer, index)
|
||||
while nth do
|
||||
local timer = world:get(entity, jecs.pair(ct.Timer, nth))
|
||||
local elapsed = timer.elapsed + dt
|
||||
if elapsed >= timer.duration then
|
||||
world:add(entity, ct.Destroy)
|
||||
end
|
||||
timer.elapsed = elapsed
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const entity = world.entity();
|
||||
print(world.contains(entity));
|
||||
print(world.contains(1));
|
||||
print(world.contains(2));
|
||||
|
||||
// Outputs:
|
||||
// true
|
||||
// true
|
||||
// false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
|
||||
## parent
|
||||
|
||||
Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
|
||||
|
||||
```luau
|
||||
function World:parent(
|
||||
child: Entity -- The child ID to find the parent of
|
||||
): Entity? -- Returns the parent of the child
|
||||
```
|
||||
|
||||
This operation is the same as calling:
|
||||
|
||||
```luau
|
||||
world:target(entity, jecs.ChildOf, 0)
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
|
||||
## remove
|
||||
|
||||
Removes a component (ID) from an entity
|
||||
|
||||
```luau
|
||||
function World:remove<T>(
|
||||
entity: Entity,
|
||||
component: Id<T>
|
||||
): void
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local IsMoving = world:component()
|
||||
|
||||
local entity = world:entity()
|
||||
world:add(entity, IsMoving)
|
||||
|
||||
print(world:has(entity, IsMoving))
|
||||
|
||||
world:remove(entity, IsMoving)
|
||||
print(world:has(entity, IsMoving))
|
||||
|
||||
-- Outputs:
|
||||
-- true
|
||||
-- false
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const IsMoving = world.component();
|
||||
|
||||
const entity = world.entity();
|
||||
world.add(entity, IsMoving);
|
||||
|
||||
print(world.has(entity, IsMoving));
|
||||
|
||||
world.remove(entity, IsMoving);
|
||||
print(world.has(entity, IsMoving));
|
||||
|
||||
// Outputs:
|
||||
// true
|
||||
// false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## delete
|
||||
|
||||
Deletes an entity and all of its related components and relationships.
|
||||
|
||||
```luau
|
||||
function World:delete(
|
||||
entity: Entity
|
||||
): void
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
|
||||
```luau [luau]
|
||||
local entity = world:entity()
|
||||
print(world:contains(entity))
|
||||
|
||||
world:delete(entity)
|
||||
|
||||
print(world:contains(entity))
|
||||
|
||||
-- Outputs:
|
||||
-- true
|
||||
-- false
|
||||
```
|
||||
|
||||
```ts [typescript]
|
||||
const entity = world.entity();
|
||||
print(world.has(entity));
|
||||
|
||||
world.delete(entity);
|
||||
|
||||
print(world.has(entity));
|
||||
|
||||
// Outputs:
|
||||
// true
|
||||
// false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## clear
|
||||
|
||||
Clears all of the components and relationships of the entity without deleting it.
|
||||
|
||||
```luau
|
||||
function World:clear(
|
||||
entity: Entity
|
||||
): void
|
||||
```
|
||||
|
||||
## each
|
||||
|
||||
Iterate over all entities with the specified component.
|
||||
Useful when you only need the entity for a specific ID and you want to avoid creating a query.
|
||||
|
||||
```luau
|
||||
function World:each(
|
||||
component: Id -- The component ID
|
||||
): () -> Entity
|
||||
```
|
||||
|
||||
Example:
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local id = world:component()
|
||||
for entity in world:each(id) do
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
```ts [typescript]
|
||||
const id = world.component();
|
||||
for (const entity of world.each(id)) {
|
||||
// Do something
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
## children
|
||||
|
||||
Iterate entities in root of parent
|
||||
|
||||
```luau
|
||||
function World:children(
|
||||
parent: Entity -- The parent entity
|
||||
): () -> Entity
|
||||
```
|
||||
|
||||
This is the same as calling:
|
||||
|
||||
```luau
|
||||
world:each(pair(ChildOf, parent))
|
||||
```
|
||||
|
||||
## range
|
||||
|
||||
Enforces a check for entities to be created within a desired range.
|
||||
```luau
|
||||
function World:range(
|
||||
range_begin: number -- The starting point,
|
||||
range_end: number? -- The end point (optional)
|
||||
)
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
world:range(1000, 5000) -- Entities will be created with IDs 1000-5000
|
||||
|
||||
local entity = world:entity()
|
||||
print(entity) -- Will be >= 1000 and < 5000
|
||||
```
|
||||
```ts [typescript]
|
||||
world.range(1000, 5000) // Entities will be created with IDs 1000-5000
|
||||
|
||||
const entity = world.entity()
|
||||
print(entity) // Will be >= 1000 and < 5000
|
||||
```
|
||||
:::
|
||||
|
||||
## parent
|
||||
|
||||
Gets the parent entity of the specified entity using the built-in `ChildOf` relationship.
|
||||
|
||||
```luau
|
||||
function World:parent(
|
||||
entity: Entity
|
||||
): Entity? -- Returns the parent entity or nil if no parent
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local parent = world:entity()
|
||||
local child = world:entity()
|
||||
|
||||
world:add(child, pair(jecs.ChildOf, parent))
|
||||
|
||||
local retrieved_parent = world:parent(child)
|
||||
print(retrieved_parent == parent) -- true
|
||||
```
|
||||
```ts [typescript]
|
||||
const parent = world.entity()
|
||||
const child = world.entity()
|
||||
|
||||
world.add(child, pair(jecs.ChildOf, parent))
|
||||
|
||||
const retrievedParent = world.parent(child)
|
||||
print(retrievedParent === parent) // true
|
||||
```
|
||||
:::
|
||||
|
||||
## contains
|
||||
|
||||
Checks if an entity or component (id) exists and is alive in the world.
|
||||
|
||||
```luau
|
||||
function World:contains(
|
||||
entity: Entity
|
||||
): boolean
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local entity = world:entity()
|
||||
print(world:contains(entity)) -- true
|
||||
|
||||
world:delete(entity)
|
||||
print(world:contains(entity)) -- false
|
||||
```
|
||||
```ts [typescript]
|
||||
const entity = world.entity()
|
||||
print(world.contains(entity)) // true
|
||||
|
||||
world.delete(entity)
|
||||
print(world.contains(entity)) // false
|
||||
```
|
||||
:::
|
||||
|
||||
## exists
|
||||
|
||||
Checks if the entity ID exists regardless of whether it is alive or not. Useful to know if the ID is occupied in the entity index.
|
||||
|
||||
```luau
|
||||
function World:exists(
|
||||
entity: Entity
|
||||
): boolean
|
||||
```
|
||||
|
||||
## cleanup
|
||||
|
||||
Cleans up empty archetypes.
|
||||
|
||||
```luau
|
||||
function World:cleanup(): void
|
||||
```
|
||||
|
||||
:::info
|
||||
It is recommended to profile the optimal interval you should cleanup because it varies completely from game to game.
|
||||
|
||||
Here are a couple of reasons from Sander Mertens:
|
||||
- some applications are memory constrained, so any wasted memory on empty
|
||||
archetypes has to get cleaned up
|
||||
- many archetypes can get created during game startup but aren't used later
|
||||
on, so it would be wasteful to keep them around
|
||||
- empty archetypes can slow queries down, especially if there are many more
|
||||
empty ones than non-empty ones
|
||||
- if the total number of component permutations (/relationships) is too
|
||||
high, you have no choice but to periodically cleanup empty archetypes
|
||||
:::
|
||||
|
||||
Example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local entity = world:entity()
|
||||
world:delete(entity)
|
||||
|
||||
-- Cleanup is usually automatic, but can be called manually
|
||||
world:cleanup()
|
||||
```
|
||||
```ts [typescript]
|
||||
const entity = world.entity()
|
||||
world.delete(entity)
|
||||
|
||||
// Cleanup is usually automatic, but can be called manually
|
||||
world.cleanup()
|
||||
```
|
||||
:::
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
---
|
||||
# https://vitepress.dev/reference/default-theme-home-page
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: "Jecs"
|
||||
tagline: Just a stupidly fast ECS
|
||||
image:
|
||||
src: /jecs_logo.svg
|
||||
alt: Jecs logo
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Overview
|
||||
link: learn/overview.md
|
||||
- theme: alt
|
||||
text: API References
|
||||
link: /api/jecs.md
|
||||
|
||||
features:
|
||||
- title: Stupidly Fast
|
||||
icon: 🔥
|
||||
details: Iterates 800,000 entities at 60 frames per second.
|
||||
- title: Strictly Typed API
|
||||
icon: 🔒
|
||||
details: Has typings for both Luau and Typescript.
|
||||
- title: Zero-Dependencies
|
||||
icon: 📦
|
||||
details: Jecs doesn't rely on anything other than itself.
|
||||
---
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
# Code Coverage Reports
|
||||
|
||||
All of the code coverage reports can be found here:
|
||||
|
||||
[Overview](/jecs/coverage/index.html){target="_self"}
|
||||
|
||||
[jecs.luau](/jecs/coverage/jecs.luau.html){target="_self"}
|
||||
|
||||
[ANSI](/jecs/coverage/ansi.luau.html){target="_self"}
|
||||
|
||||
[Entity Visualiser](/jecs/coverage/entity_visualiser.luau.html){target="_self"}
|
||||
|
||||
[Lifetime Tracker](/jecs/coverage/lifetime_tracker.luau.html){target="_self"}
|
||||
|
||||
[Testkit](/jecs/coverage/testkit.luau.html){target="_self"}
|
||||
|
||||
[Tests](/jecs/coverage/tests.luau.html){target="_self"}
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
# Contribution Guidelines
|
||||
|
||||
Whether you found an issue, or want to make a change to jecs, we'd love to hear back from the community on what features you want or bugs you've run into.
|
||||
|
||||
There's a few different ways you can go about this.
|
||||
|
||||
## Creating an Issue
|
||||
|
||||
This is what you should be filing if you have a bug you want to report.
|
||||
|
||||
[Click here](https://github.com/Ukendio/jecs/issues/new/choose) to file a bug report. We have a few templates ready for the most common issue types.
|
||||
|
||||
Additionally, see the [Submitting Issues](../contributing/issues) page for more information.
|
||||
|
||||
## Creating a Pull Request
|
||||
|
||||
This is what you should be filing if you have a change you want to merge into the main project.
|
||||
|
||||
[Click here](https://github.com/Ukendio/jecs/compare) to select the branch you want to merge from.
|
||||
|
||||
Additionally, see the [Submitting Pull Requests](../contributing/pull-requests) page for more information.
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
# Submitting Issues
|
||||
|
||||
When you're submitting an issue, generally they fall into a few categories:
|
||||
|
||||
## Bug
|
||||
|
||||
We need some information to figure out what's going wrong. At a minimum, you need to tell us:
|
||||
|
||||
(1) What's supposed to happen
|
||||
|
||||
(2) What actually happened
|
||||
|
||||
(3) Steps to reproduce
|
||||
|
||||
|
||||
Stack traces and other useful information that you find make a bug report more likely to be fixed.
|
||||
|
||||
Consult the template for a bug report if you don't know or have questions about how to format this.
|
||||
|
||||
## Documentation
|
||||
|
||||
Depending on how you go about it, this can be done as a [Pull Request](../contributing/pull-requests) instead of an issue. Generally, we need to know what was wrong, what you changed, and how it improved the documentation if it isn't obvious.
|
||||
|
||||
We just need to know what's wrong. You should fill out a [PR](../contributing/pull-requests) if you know what should be there instead.
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
# Submitting Pull Requests
|
||||
|
||||
When submitting a Pull Request, there's a few reasons to do so:
|
||||
|
||||
|
||||
## Documentation
|
||||
|
||||
If there's something to change with the documentation, you should follow a similar format to this example:
|
||||
|
||||
An example of an appropriate typo-fixing PR would be:
|
||||
|
||||
>**Brief Description of your Changes**
|
||||
>
|
||||
>I fixed a couple of typos found in the /contributing/issues.md file.
|
||||
>
|
||||
>**Impact of your Changes**
|
||||
>
|
||||
>- Documentation is more clear and readable for the users.
|
||||
>
|
||||
>**Tests Performed**
|
||||
>
|
||||
>Ran `vitepress dev docs` and verified it was built successfully.
|
||||
>
|
||||
>**Additional Comments**
|
||||
>
|
||||
>[At Discretion]
|
||||
|
||||
## Change in Behavior
|
||||
|
||||
An example of an appropriate PR that adds a new feature would be:
|
||||
|
||||
>
|
||||
>**Brief Description of your Changes**
|
||||
>
|
||||
>I added `jecs.best_function`, which gives everyone who uses the module an immediate boost in concurrent player counts. (this is a joke)
|
||||
>
|
||||
>**Impact of your Changes**
|
||||
>
|
||||
>- jecs functionality is extended to better fit the needs of the community [explain why].
|
||||
>
|
||||
>**Tests Performed**
|
||||
>
|
||||
>Added a few test cases to ensure the function runs as expected [link to changes].
|
||||
>
|
||||
>**Additional Comments**
|
||||
>
|
||||
>[At Discretion]
|
||||
|
||||
## Addons
|
||||
|
||||
If you made something you think should be included into the [resources page](../../resources), let us know!
|
||||
|
||||
We have tons of examples of libraries and other tools which can be used in conjunction with jecs on this page.
|
||||
|
||||
One example of a PR that would be accepted is:
|
||||
|
||||
>**Brief Description of your Changes**
|
||||
>
|
||||
>I added `jecs observers` to the addons page.
|
||||
>
|
||||
>**Impact of your Changes**
|
||||
>
|
||||
>- jecs observers are a different and important way of handling queries which benefit the users of jecs by [explain why your tool benefits users here]
|
||||
>
|
||||
>- [talk about why you went with this design instead of maybe an alternative]
|
||||
>
|
||||
>**Tests Performed**
|
||||
>
|
||||
> I used this tool in conjunction with jecs and ensured it works as expected.
|
||||
>
|
||||
> [If you wrote unit tests for your tool, mention it here.]
|
||||
>
|
||||
>**Additional Comments**
|
||||
>
|
||||
>[At Discretion]
|
||||
|
||||
Keep in mind the list on the addons page is *not* exhaustive. If you came up with a tool that doesn't fit into any of the categories listed, we still want to hear from you!
|
||||
|
|
@ -1,718 +0,0 @@
|
|||
# Introduction
|
||||
Jecs is a standalone entity-component-system module written in Luau.
|
||||
ECS ("entity-component-system") describes one way to write games in a more data oriented design.
|
||||
|
||||
## Installation
|
||||
|
||||
Jecs supports the following installation methods using package managers:
|
||||
:::code-group
|
||||
```bash [wally]
|
||||
jecs = "ukendio/jecs@0.6.0" # Inside wally.toml
|
||||
```
|
||||
```bash [pesde]
|
||||
pesde add wally#ukendio/jecs@0.6.0
|
||||
```
|
||||
```bash [npm]
|
||||
npm i @rbxts/jecs
|
||||
```
|
||||
:::
|
||||
|
||||
Additionally an `rbxm` is published with [each release under the assets submenu](https://github.com/Ukendio/jecs/releases/latest).
|
||||
|
||||
## Hello World, Entity and Component
|
||||
It all has to start somewhere. A world stores entities and their components, and manages them. This tour will reference it for every operation.
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
local jecs = require(path/to/jecs)
|
||||
local world = jecs.world()
|
||||
```
|
||||
```typescript [typescript]
|
||||
import * as jecs from "@rbxts/jecs"
|
||||
const world = jecs.world()
|
||||
// creates a new entity with no components and returns its identifier
|
||||
const entity = world.entity()
|
||||
|
||||
// deletes an entity and all its components
|
||||
world.delete(entity)
|
||||
```
|
||||
:::
|
||||
|
||||
## Entities
|
||||
|
||||
Entities represent things in a game. In a game there may be entities of characters, buildings, projectiles, particle effects etc.
|
||||
|
||||
By itself, an entity is just an unique entity identifier without any data. An entity identifier contains information about the entity itself and its generation.
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
-- creates a new entity with no components and returns its identifier
|
||||
local entity = world:entity()
|
||||
|
||||
-- deletes an entity and all its components
|
||||
world:delete(entity)
|
||||
```
|
||||
```typescript [typescript]
|
||||
// creates a new entity with no components and returns its identifier
|
||||
const entity = world.entity()
|
||||
|
||||
// deletes an entity and all its components
|
||||
world.delete(entity)
|
||||
```
|
||||
:::
|
||||
|
||||
The `entity` member function also accepts an overload that allows you to create an entity with a desired id which bypasses the [`entity range`](#Entity-Ranges).
|
||||
|
||||
## Components
|
||||
|
||||
A component is something that is added to an entity. Components can simply tag an entity ("this entity is an `Npc`"), attach data to an entity ("this entity is at `Position` `Vector3.new(10, 20, 30)`") and create relationships between entities ("bob `Likes` alice") that may also contain data ("bob `Eats` `10` apples").
|
||||
|
||||
## Operations
|
||||
|
||||
| Operation | Description |
|
||||
| --------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `get` | Get a specific component or set of components from an entity. |
|
||||
| `add` | Adds component to an entity. If entity already has the component, `add` does nothing. |
|
||||
| `set` | Sets the value of a component for an entity. `set` behaves as a combination of `add` and `get` |
|
||||
| `remove` | Removes component from entity. If entity doesn't have the component, `remove` does nothing. |
|
||||
| `clear` | Remove all components from an entity. Clearing is more efficient than removing one by one. |
|
||||
|
||||
## Components are entities
|
||||
|
||||
In an ECS, components need to be uniquely identified. In Jecs this is done by making each component its own unique entity. This means that everything is customizable. Components are no exception
|
||||
and all of the APIs that apply to regular entities also apply to component entities.
|
||||
|
||||
If a game has a component Position and Velocity, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component trait.
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local Position = world:component() :: jecs.Entity<Vector3>
|
||||
world:set(Position, jecs.Name, "Position") -- Using regular apis to set metadata on component entities!
|
||||
|
||||
print(`{world:get(Position, jecs.Name)} is a Component: {world:has(Position, jecs.Component)}`);
|
||||
|
||||
-- Output:
|
||||
-- Position is a Component: true
|
||||
```
|
||||
```typescript [typescript]
|
||||
const Position = world.component<Vector3>();
|
||||
world.set(Position, jecs.Name, "Position") // Using regular apis to set metadata on component entities!
|
||||
|
||||
print(`${world.get(Position, jecs.Name)} is a Component: ${world.has(Position, jecs.Component)}`);
|
||||
// Output:
|
||||
// Position is a Component: true
|
||||
```
|
||||
:::
|
||||
|
||||
### Entity ranges
|
||||
Jecs reserves entity ids under a threshold (HI_COMPONENT_ID, default is 256) for components. That means that regular entities will start after this number. This number can be further specified via the `range` member function.
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
world:range(1000, 5000) -- Defines the lower and upper bounds of the entity range respectively
|
||||
|
||||
local e = world:entity()
|
||||
print(e)
|
||||
-- Output:
|
||||
-- 1000
|
||||
```
|
||||
```typescript [typescript]
|
||||
world.range(1000, 5000) // Defines the lower and upper bounds of the entity range respectively
|
||||
|
||||
const e = world.entity()
|
||||
print(e)
|
||||
// Output:
|
||||
// 1000
|
||||
```
|
||||
:::
|
||||
|
||||
### Hooks
|
||||
|
||||
Component data generally need to adhere to a specific interface, and sometimes requires side effects to run upon certain lifetime cycles. In `jecs`, there are hooks which are `component traits`, that can define the behaviour of a component and enforce invariants, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnChange` hook per component, just like you can only have a single constructor and destructor.
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local Transform = world:component()
|
||||
world:set(Transform, OnAdd, function(entity, id, data)
|
||||
-- A transform component `id` has been added with `data` to `entity`
|
||||
end)
|
||||
world:set(Transform, OnRemove, function(entity, id)
|
||||
-- A transform component `id` has been removed from `entity`
|
||||
end)
|
||||
world:set(Transform, OnChange, function(entity, id, data)
|
||||
-- A transform component `id` has been changed to `data` on `entity`
|
||||
end)
|
||||
```
|
||||
```typescript [typescript]
|
||||
const Transform = world.component();
|
||||
world.set(Transform, OnAdd, (entity, id, data) => {
|
||||
// A transform component `id` has been added with `data` to `entity`
|
||||
});
|
||||
world.set(Transform, OnRemove, (entity, id) => {
|
||||
// A transform component `id` has been removed from `entity`
|
||||
});
|
||||
world.set(Transform, OnChange, (entity, id, data) => {
|
||||
// A transform component `id` has been changed to `data` on `entity`
|
||||
});
|
||||
```
|
||||
:::
|
||||
|
||||
:::info
|
||||
Children are cleaned up before parents
|
||||
When a parent and its children are deleted, OnRemove hooks will be invoked for children first, under the condition that there are no cycles in the relationship graph of the deleted entities. This order is maintained for any relationship that has the (OnDeleteTarget, Delete) trait (see Component Traits for more details).
|
||||
|
||||
When an entity graph contains cycles, order is undefined. This includes cycles that can be formed using different relationships.
|
||||
:::
|
||||
|
||||
### 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.
|
||||
|
||||
This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
|
||||
|
||||
To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
|
||||
|
||||
#### Cleanup Traits Summary
|
||||
|
||||
| Condition | Action | Description | Use Case |
|
||||
|-----------|--------|-------------|----------|
|
||||
| `OnDelete` | `Remove` | Removes the component from all entities when the component is deleted | Default behavior, safe cleanup |
|
||||
| `OnDelete` | `Delete` | Deletes all entities that have the component when the component is deleted | Cascading deletion, dangerous |
|
||||
| `OnDeleteTarget` | `Remove` | Removes the relationship from all entities when the target is deleted | Safe relationship cleanup |
|
||||
| `OnDeleteTarget` | `Delete` | Deletes all entities that have the relationship when the target is deleted | Hierarchical deletion (e.g., parent-child) |
|
||||
|
||||
**Cleanup Actions:**
|
||||
- `Remove`: removes instances of the specified (component) id from all entities (default)
|
||||
- `Delete`: deletes all entities with specified id
|
||||
|
||||
**Cleanup Conditions:**
|
||||
- `OnDelete`: the component, tag or relationship is deleted
|
||||
- `OnDeleteTarget`: a target used with the relationship is deleted
|
||||
|
||||
#### (OnDelete, Remove)
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local Archer = world:component()
|
||||
world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
|
||||
|
||||
local e = world:entity()
|
||||
world:add(e, Archer)
|
||||
|
||||
-- This will remove Archer from e
|
||||
world:delete(Archer)
|
||||
```
|
||||
```typescript [typescript]
|
||||
const Archer = world.component();
|
||||
world.add(Archer, pair(jecs.OnDelete, jecs.Remove));
|
||||
|
||||
const e = world.entity();
|
||||
world.add(e, Archer);
|
||||
|
||||
// This will remove Archer from e
|
||||
world.delete(Archer);
|
||||
```
|
||||
:::
|
||||
|
||||
#### (OnDelete, Delete)
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local Archer = world:component()
|
||||
world:add(Archer, pair(jecs.OnDelete, jecs.Delete))
|
||||
|
||||
local e = world:entity()
|
||||
world:add(e, Archer)
|
||||
|
||||
-- This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
|
||||
world:delete(Archer)
|
||||
```
|
||||
```typescript [typescript]
|
||||
const Archer = world.component();
|
||||
world.add(Archer, pair(jecs.OnDelete, jecs.Delete));
|
||||
|
||||
const e = world.entity();
|
||||
world.add(e, Archer);
|
||||
|
||||
// This will delete entity e because the Archer component has a (OnDelete, Delete) cleanup trait
|
||||
world.delete(Archer);
|
||||
```
|
||||
:::
|
||||
|
||||
#### (OnDeleteTarget, Remove)
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local OwnedBy = world:component()
|
||||
world:add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove))
|
||||
local loot = world:entity()
|
||||
local player = world:entity()
|
||||
world:add(loot, pair(OwnedBy, player))
|
||||
|
||||
-- This will remove (OwnedBy, player) from loot
|
||||
world:delete(player)
|
||||
```
|
||||
```typescript [typescript]
|
||||
const OwnedBy = world.component();
|
||||
world.add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove));
|
||||
const loot = world.entity();
|
||||
const player = world.entity();
|
||||
world.add(loot, pair(OwnedBy, player));
|
||||
|
||||
// This will remove (OwnedBy, player) from loot
|
||||
world.delete(player);
|
||||
```
|
||||
:::
|
||||
#### (OnDeleteTarget, Delete)
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local ChildOf = world:component()
|
||||
world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
|
||||
|
||||
local parent = world:entity()
|
||||
local child = world:entity()
|
||||
world:add(child, pair(ChildOf, parent))
|
||||
|
||||
-- This will delete both parent and child
|
||||
world:delete(parent)
|
||||
```
|
||||
```typescript [typescript]
|
||||
const ChildOf = world.component();
|
||||
world.add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete));
|
||||
|
||||
const parent = world.entity();
|
||||
const child = world.entity();
|
||||
world.add(child, pair(ChildOf, parent));
|
||||
|
||||
// This will delete both parent and child
|
||||
world.delete(parent);
|
||||
```
|
||||
:::
|
||||
|
||||
## Preregistration
|
||||
|
||||
By default, components being registered on runtime is useful for how dynamic it can be. But, sometimes being able to register components without having the world instance is useful.
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local Position = jecs.component() :: jecs.Entity<Vector3>
|
||||
|
||||
jecs.world() -- Position gets registered here
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
import { world } from "@rbxts/jecs"
|
||||
const Position = jecs.component<Vector3>();
|
||||
|
||||
world() // Position gets registered here
|
||||
```
|
||||
:::
|
||||
|
||||
However, if you try to set metadata, you will find that this doesn't work without the world instance. Instead, jecs offers a `meta` member function that can forward declare its metadata.
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
jecs.meta(Position, jecs.Name, "Position")
|
||||
|
||||
jecs.world() -- Position gets registered here with its name "Position"
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
import { world } from "@rbxts/jecs"
|
||||
|
||||
jecs.meta(Position, jecs.Name, "Position")
|
||||
|
||||
world() // Position gets registered here with its name "Position"
|
||||
```
|
||||
:::
|
||||
|
||||
### Singletons
|
||||
|
||||
Singletons are components for which only a single instance
|
||||
exists on the world. They can be accessed on the
|
||||
world directly and do not require providing an entity.
|
||||
Singletons are useful for global game resources, such as
|
||||
game state, a handle to a physics engine or a network socket. An example:
|
||||
|
||||
::: code-group
|
||||
```luau [luau]
|
||||
local TimeOfDay = world:component() :: jecs.Entity<number>
|
||||
world:set(TimeOfDay, TimeOfDay, 0.5)
|
||||
local t = world:get(TimeOfDay, TimeOfDay)
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
const TimeOfDay = world.component<number>();
|
||||
world.set(TimeOfDay, TimeOfDay, 0.5);
|
||||
const t = world.get(TimeOfDay, TimeOfDay);
|
||||
```
|
||||
:::
|
||||
|
||||
# Queries
|
||||
|
||||
Queries enable games to quickly find entities that satifies provided conditions.
|
||||
:::code-group
|
||||
|
||||
```luau [luau]
|
||||
for _ in world:query(Position, Velocity) do end
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
for (const [_] of world.query(Position, Velocity)) {
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
In `jecs`, queries can do anything from returning entities that match a simple list of components, to matching against entity graphs.
|
||||
|
||||
This manual contains a full overview of the query features available in Jecs. Some of the features of Jecs queries are:
|
||||
|
||||
- Queries have support for relationships pairs which allow for matching against entity graphs without having to build complex data structures for it.
|
||||
- Queries support filters such as [`query:with(...)`](../api/query.md#with) if entities are required to have the components but you don’t actually care about components value. And [`query:without(...)`](../api/query.md#without) which selects entities without the components.
|
||||
- Queries can be drained or reset on when called, which lets you choose iterator behaviour.
|
||||
- Queries can be called with any ID, including entities created dynamically, this is useful for pairs.
|
||||
- Queries are already fast but can be futher inlined via [`query:archetypes()`](../api/query.md#archetypes) for maximum performance to eliminate function call overhead which is roughly 60-80% of the cost for iteration.
|
||||
|
||||
## Performance and Caching
|
||||
|
||||
Understanding the basic architecture of queries helps to make the right tradeoffs when using queries in games.
|
||||
The biggest impact on query performance is whether a query is cached or not.
|
||||
This section goes over what caching is, how it can be used and when it makes sense to use it.
|
||||
|
||||
### Caching: what is it?
|
||||
|
||||
Jecs is an archetype ECS, which means that entities with exactly the same components are
|
||||
grouped together in an "archetype". Archetypes are created on the fly
|
||||
whenever a new component combination is created in the ECS. For example:
|
||||
|
||||
:::code-group
|
||||
|
||||
```luau [luau]
|
||||
local e1 = world:entity()
|
||||
world:set(e1, Position, Vector3.new(10, 20, 30)) -- create archetype [Position]
|
||||
world:set(e1, Velocity, Vector3.new(1, 2, 3)) -- create archetype [Position, Velocity]
|
||||
|
||||
local e2 = world:entity()
|
||||
world:set(e2, Position, Vector3.new(10, 20, 30)) -- archetype [Position] already exists
|
||||
world:set(e2, Velocity, Vector3.new(1, 2, 3)) -- archetype [Position, Velocity] already exists
|
||||
world:set(e3, Mass, 100) -- create archetype [Position, Velocity, Mass]
|
||||
|
||||
-- e1 is now in archetype [Position, Velocity]
|
||||
-- e2 is now in archetype [Position, Velocity, Mass]
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
const e1 = world.entity();
|
||||
world.set(e1, Position, new Vector3(10, 20, 30)); // create archetype [Position]
|
||||
world.set(e1, Velocity, new Vector3(1, 2, 3)); // create archetype [Position, Velocity]
|
||||
|
||||
const e2 = world.entity();
|
||||
world.set(e2, Position, new Vector3(10, 20, 30)); // archetype [Position] already exists
|
||||
world.set(e2, Velocity, new Vector3(1, 2, 3)); // archetype [Position, Velocity] already exists
|
||||
world.set(e3, Mass, 100); // create archetype [Position, Velocity, Mass]
|
||||
|
||||
// e1 is now in archetype [Position, Velocity]
|
||||
// e2 is now in archetype [Position, Velocity, Mass]
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Archetypes are important for queries. Since all entities in an archetype have the same components, and a query matches entities with specific components, a query can often match entire archetypes instead of individual entities. This is one of the main reasons why queries in an archetype ECS are fast.
|
||||
|
||||
The second reason that queries in an archetype ECS are fast is that they are cheap to cache. While an archetype is created for each unique component combination, games typically only use a finite set of component combinations which are created quickly after game assets are loaded.
|
||||
|
||||
This means that instead of searching for archetypes each time a query is evaluated, a query can instead cache the list of matching archetypes. This is a cheap cache to maintain: even though entities can move in and out of archetypes, the archetypes themselves are often stable.
|
||||
|
||||
If none of that made sense, the main thing to remember is that a cached query does not actually have to search for entities. Iterating a cached query just means iterating a list of prematched results, and this is really, really fast.
|
||||
|
||||
### Tradeoffs
|
||||
|
||||
Jecs has both cached and uncached queries. If cached queries are so fast, why even bother with uncached queries? There are four main reasons:
|
||||
|
||||
- Cached queries are really fast to iterate, but take more time to create because the cache must be initialized first.
|
||||
- Cached queries add overhead to archetype creation/deletion, as these changes have to get propagated to caches.
|
||||
- While caching archetypes is fast, some query features require matching individual entities, which are not efficient to cache (and aren't cached).
|
||||
|
||||
As a rule of thumb, if you have a query that is evaluated each frame (as is typically the case with systems), they will benefit from being cached. If you need to create a query ad-hoc, an uncached query makes more sense.
|
||||
|
||||
Ad-hoc queries are often necessary when a game needs to find entities that match a condition that is only known at runtime, for example to find all child entities for a specific parent.
|
||||
|
||||
### Components
|
||||
|
||||
A component is any single ID that can be added to an entity. This includes tags and regular entities, which are IDs that do not have the builtin `Component` component. To match a query, an entity must have all the requested components. An example:
|
||||
|
||||
```luau
|
||||
local e1 = world:entity()
|
||||
world:add(e1, Position)
|
||||
|
||||
local e2 = world:entity()
|
||||
world:add(e2, Position)
|
||||
world:add(e2, Velocity)
|
||||
|
||||
local e3 = world:entity()
|
||||
world:add(e3, Position)
|
||||
world:add(e3, Velocity)
|
||||
world:add(e3, Mass)
|
||||
|
||||
```
|
||||
|
||||
Only entities `e2` and `e3` match the query Position, Velocity.
|
||||
|
||||
### Wildcards
|
||||
|
||||
Jecs currently only supports the `Any` type of wildcards which a single result for the first component that it matches.
|
||||
|
||||
When using the `Any` type wildcard it is undefined which component will be matched, as this can be influenced by other parts of the query. It is guaranteed that iterating the same query twice on the same dataset will produce the same result.
|
||||
|
||||
If you want to iterate multiple targets for the same relation on a pair, then use [`world:target`](../api/world.md#target)
|
||||
|
||||
Wildcards are particularly useful when used in combination with pairs (next section).
|
||||
|
||||
### Pairs
|
||||
|
||||
A pair is an ID that encodes two elements. Pairs, like components, can be added to entities and are the foundation for [`Relationships`](#relationships).
|
||||
|
||||
The elements of a pair are allowed to be wildcards. When a query pair returns an `Any` type wildcard, the query returns at most a single matching pair on an entity.
|
||||
|
||||
The following sections describe how to create queries for pairs in the different language bindings.
|
||||
|
||||
:::code-group
|
||||
|
||||
```luau [luau]
|
||||
local Likes = world:entity()
|
||||
local bob = world:entity()
|
||||
for _ in world:query(pair(Likes, bob)) do end
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
const Likes = world.entity();
|
||||
const bob = world.entity();
|
||||
for (const [_] of world.query(pair(Likes, bob))) {
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
When a query pair contains a wildcard, the `world:target()` function can be used to determine the target of the pair element that matched the query:
|
||||
|
||||
:::code-group
|
||||
|
||||
```luau [luau]
|
||||
for id in world:query(pair(Likes, jecs.Wildcard)) do
|
||||
print(`entity {getName(id)} likes {getName(world, world:target(id, Likes))}`)
|
||||
end
|
||||
```
|
||||
|
||||
```typescript [typescript]
|
||||
const Likes = world.entity();
|
||||
const bob = world.entity();
|
||||
for (const [_] of world.query(pair(Likes, jecs.Wildcard))) {
|
||||
print(`entity ${getName(id)} likes ${getName(world.target(id, Likes))}`);
|
||||
}
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Filters
|
||||
|
||||
Filters are extensions to queries which allow you to select entities from a more complex pattern but you don't actually care about the component values.
|
||||
|
||||
The following filters are supported by queries:
|
||||
|
||||
| Identifier | Description |
|
||||
| ---------- | ----------------------------------- |
|
||||
| With | Must match with all terms. |
|
||||
| Without | Must not match with provided terms. |
|
||||
|
||||
## Relationships
|
||||
Relationships makes it possible to describe entity graphs natively in ECS.
|
||||
|
||||
Adding/removing relationships is similar to adding/removing regular components, with as difference that instead of a single component id, a relationship adds a pair of two things to an entity. In this pair, the first element represents the relationship (e.g. "Eats"), and the second element represents the relationship target (e.g. "Apples").
|
||||
|
||||
Relationships can be used to describe many things, from hierarchies to inventory systems to trade relationships between players in a game. The following sections go over how to use relationships, and what features they support.
|
||||
|
||||
### Definitions
|
||||
|
||||
Name | Description
|
||||
----------|------------
|
||||
Id | An id that can be added and removed
|
||||
Component | Id with a single element (same as an entity id)
|
||||
Relationship | Used to refer to first element of a pair
|
||||
Target | Used to refer to second element of a pair
|
||||
Source | Entity to which an id is added
|
||||
|
||||
### Relationship queries
|
||||
There are a number of ways a game can query for relationships. The following kinds of queries are available for all (unidirectional) relationships, and are all constant time:
|
||||
|
||||
Test if entity has a relationship pair
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
world:has(bob, pair(Eats, Apples))
|
||||
```
|
||||
```typescript [typescript]
|
||||
world.has(bob, pair(Eats, Apples))
|
||||
```
|
||||
:::
|
||||
|
||||
Test if entity has a relationship wildcard
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
world:has(bob, pair(Eats, jecs.Wildcard))
|
||||
```
|
||||
```typescript [typescript]
|
||||
world.has(bob, pair(Eats, jecs.Wildcard))
|
||||
```
|
||||
:::
|
||||
|
||||
Get parent for entity
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
world:parent(bob)
|
||||
```
|
||||
```typescript [typescript]
|
||||
world.parent(bob)
|
||||
```
|
||||
:::
|
||||
|
||||
Find first target of a relationship for entity
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
world:target(bob, Eats)
|
||||
```
|
||||
```typescript [typescript]
|
||||
world.target(bob, Eats)
|
||||
```
|
||||
:::
|
||||
|
||||
Find all entities with a pair
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
for id in world:query(pair(Eats, Apples)) do
|
||||
-- ...
|
||||
end
|
||||
```
|
||||
```typescript [typescript]
|
||||
for (const [id] of world.query(pair(Eats, Apples))) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
Find all entities with a pair wildcard
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
for id in world:query(pair(Eats, jecs.Wildcard)) do
|
||||
local food = world:target(id, Eats) -- Apples, ...
|
||||
end
|
||||
```
|
||||
```typescript [typescript]
|
||||
for (const [id] of world.query(pair(Eats, jecs.Wildcard))) {
|
||||
const food = world.target(id, Eats) // Apples, ...
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
Iterate all children for a parent
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
for child in world:query(pair(jecs.ChildOf, parent)) do
|
||||
-- ...
|
||||
end
|
||||
```
|
||||
```typescript [typescript]
|
||||
for (const [child] of world.query(pair(jecs.ChildOf, parent))) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### Relationship components
|
||||
|
||||
Relationship pairs, just like regular component, can be associated with data.
|
||||
|
||||
:::code-group
|
||||
```luau [luau]
|
||||
local Position = world:component()
|
||||
local Eats = world:component()
|
||||
local Apples = world:entity()
|
||||
local Begin = world:entity()
|
||||
local End = world:entity()
|
||||
|
||||
local e = world:entity()
|
||||
world:set(e, pair(Eats, Apples), { amount = 1 })
|
||||
|
||||
world:set(e, pair(Begin, Position), Vector3.new(0, 0, 0))
|
||||
world:set(e, pair(End, Position), Vector3.new(10, 20, 30))
|
||||
|
||||
world:add(e, pair(jecs.ChildOf, Position))
|
||||
|
||||
```
|
||||
```typescript [typescript]
|
||||
const Position = world.component()
|
||||
const Eats = world.component()
|
||||
const Apples = world.entity()
|
||||
const Begin = world.entity()
|
||||
const End = world.entity()
|
||||
|
||||
const e = world.entity()
|
||||
world.set(e, pair(Eats, Apples), { amount: 1 })
|
||||
|
||||
world.set(e, pair(Begin, Position), new Vector3(0, 0, 0))
|
||||
world.set(e, pair(End, Position), new Vector3(10, 20, 30))
|
||||
|
||||
world.add(e, pair(jecs.ChildOf, Position))
|
||||
```
|
||||
:::
|
||||
|
||||
### Relationship wildcards
|
||||
|
||||
When querying for relationship pairs, it is often useful to be able to find all instances for a given relationship or target. To accomplish this, an game can use wildcard expressions.
|
||||
|
||||
Wildcards may used for the relationship or target part of a pair
|
||||
|
||||
```luau
|
||||
pair(Likes, jecs.Wildcard) -- Matches all Likes relationships
|
||||
pair(jecs.Wildcard, Alice) -- Matches all relationships with Alice as target
|
||||
```
|
||||
|
||||
### Relationship performance
|
||||
The ECS storage needs to know two things in order to store components for entities:
|
||||
- Which IDs are associated with an entity
|
||||
- Which types are associated with those ids
|
||||
Ids represent anything that can be added to an entity. An ID that is not associated with a type is called a tag. An ID associated with a type is a component. For regular components, the ID is a regular entity that has the builtin `Component` component.
|
||||
|
||||
### Storing relationships
|
||||
Relationships do not fundamentally change or extend the capabilities of the storage. Relationship pairs are two elements encoded into a single 53-bit ID, which means that on the storage level they are treated the same way as regular component IDs. What changes is the function that determines which type is associated with an id. For regular components this is simply a check on whether an entity has `Component`. To support relationships, new rules are added to determine the type of an id.
|
||||
|
||||
Because of this, adding/removing relationships to entities has the same performance as adding/removing regular components. This becomes more obvious when looking more closely at a function that adds a relationship pair.
|
||||
|
||||
### Fragmentation
|
||||
Fragmentation is a property of archetype-based ECS implementations where entities are spread out over more archetypes as the number of different component combinations increases. The overhead of fragmentation is visible in two areas:
|
||||
- Archetype creation
|
||||
- Queries (queries have to match & iterate more archetypes)
|
||||
Games that make extensive use of relationships might observe high levels of fragmentation, as relationships can introduce many different combinations of components. While the Jecs storage is optimized for supporting large amounts (hundreds of thousands) of archetypes, fragmentation is a factor to consider when using relationships.
|
||||
|
||||
Union relationships are planned along with other improvements to decrease the overhead of fragmentation introduced by relationships.
|
||||
|
||||
### Archetype Creation
|
||||
|
||||
When an ID added to an entity is deleted, all references to that ID are deleted from the storage. For example, when the component Position is deleted it is removed from all entities, and all archetypes with the Position component are deleted. While not unique to relationships, it is more common for relationships to trigger cleanup actions, as relationship pairs contain regular entities.
|
||||
|
||||
The opposite is also true. Because relationship pairs can contain regular entities which can be created on the fly, archetype creation is more common than in games that do not use relationships. While Jecs is optimized for fast archetypes creation, creating and cleaning up archetypes is inherently more expensive than creating/deleting an entity. Therefore archetypes creation is a factor to consider, especially for games that make extensive use of relationships.
|
||||
|
||||
### Indexing
|
||||
|
||||
To improve the speed of evaluating queries, Jecs has indices that store all archetypes for a given component ID. Whenever a new archetype is created, it is registered with the indices for the IDs the archetype has, including IDs for relationship pairs.
|
||||
|
||||
While registering an archetype for a relationship index is not more expensive than registering an archetype for a regular index, an archetype with relationships has to also register itself with the appropriate wildcard indices for its relationships. For example, an archetype with relationship `pair(Likes, Apples)` registers itself with the `pair(Likes, Apples)`, `pair(Likes, jecs.Wildcard)` and `pair(jecs.Wildcard, Apples)` indices. For this reason, creating new archetypes with relationships has a higher overhead than an archetype without relationships.
|
||||
|
||||
This page takes wording and terminology directly from Flecs, the first ECS with full support for [Entity Relationships](https://www.flecs.dev/flecs/md_docs_2Relationships.html).
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [API Reference](../api/jecs.md) - Complete API documentation
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="1080" height="1080" viewBox="0 0 1080 1080" xml:space="preserve">
|
||||
<desc>Created with Fabric.js 5.2.4</desc>
|
||||
<defs>
|
||||
</defs>
|
||||
<rect x="0" y="0" width="100%" height="100%" fill="transparent"></rect>
|
||||
<g transform="matrix(1 0 0 1 540 540)" id="09ac800d-29f3-4193-b9f5-faf19e8b1726" >
|
||||
<rect style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(255,255,255); fill-rule: nonzero; opacity: 1; visibility: hidden;" vector-effect="non-scaling-stroke" x="-540" y="-540" rx="0" ry="0" width="1080" height="1080" />
|
||||
</g>
|
||||
<g transform="matrix(Infinity NaN NaN Infinity 0 0)" id="619f0364-53a0-4caa-97e3-8f543e0cc17f" >
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(17.7 0 0 17.7 540 540)" >
|
||||
<g style="" vector-effect="non-scaling-stroke" >
|
||||
<g transform="matrix(1 0 0 1 -18.25 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: nonzero; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-5, -9)" d="M 5 14 C 5.8 14 6 13.3333 6 13 L 6 4 L 0 4 L 0 0 L 6 0 L 10 0 L 10 13 C 10 17 6.66667 18 5 18 L 0 18 L 0 14 L 5 14 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 16.75 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: nonzero; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-40, -9)" d="M 46.5 4 L 46.5 0 L 39 0 C 37.1667 0 33.5 1.1 33.5 5.5 C 33.5 9.9 36.8333 11 38.5 11 L 41 11 C 41.5 11 42.5 11.3 42.5 12.5 C 42.5 13.7 41.5 14 41 14 L 33.5 14 L 33.5 18 L 41.5 18 C 43.1667 18 46.5 16.9 46.5 12.5 C 46.5 8.1 43.1667 7 41.5 7 L 39 7 C 38.5 7 37.5 6.7 37.5 5.5 C 37.5 4.3 38.5 4 39 4 L 46.5 4 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 3.25 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: evenodd; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-26.5, -9)" d="M 32.5 0 L 32.5 4 L 30.5 4 C 28.5 4 24.5 5 24.5 9 C 24.5 11.0835 25.5853 12.3531 26.9078 13.0914 L 22.4606 14.661 C 21.2893 13.3156 20.5 11.4775 20.5 9 C 20.5 1.8 27.1667 0 30.5 0 L 32.5 0 Z M 24.4656 16.3357 C 26.5037 17.5803 28.8905 18 30.5 18 L 32.5 18 L 32.5 14 L 31.0833 14 L 24.4656 16.3357 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 -5 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: evenodd; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-18.25, -9)" d="M 25.3793 0 C 24.766 0.241156 24.1568 0.53354 23.571 0.885014 C 22.1712 1.72492 20.9038 2.91123 20.0606 4.5 L 11 4.5 L 11 0 L 25.3793 0 Z M 25.5 4.39421 C 25.445 4.42876 25.3906 4.46402 25.3368 4.5 L 25.5 4.5 L 25.5 4.39421 Z M 20.0606 13.5 C 20.9038 15.0888 22.1712 16.2751 23.571 17.115 C 24.1568 17.4665 24.766 17.7588 25.3793 18 L 11 18 L 11 13.5 L 20.0606 13.5 Z M 19.1854 7 C 19.0649 7.62348 19 8.28956 19 9 C 19 9.71044 19.0649 10.3765 19.1854 11 L 11 11 L 11 7 L 19.1854 7 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.9 KiB |
69
docs/public/coverage/ansi.luau.html
vendored
69
docs/public/coverage/ansi.luau.html
vendored
|
|
@ -1,69 +0,0 @@
|
|||
<html><head>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
|
||||
<style>
|
||||
body { font-family: monospace; text-align: center; }
|
||||
#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
|
||||
#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
|
||||
#funcTable th { background-color: #ddd; }
|
||||
#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
|
||||
.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
|
||||
.nonzero-hits { color: green; font-weight: bold; }
|
||||
.low-hits { background-color: #ffe6b3; }
|
||||
.high-hits { background-color: #cfc; }
|
||||
.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
|
||||
table.table { font-size: 14px; border-collapse: collapse; }
|
||||
table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
|
||||
table.table tr { height: auto; }
|
||||
</style></head><body>
|
||||
<h1 class="text-center">ansi.luau Coverage</h1>
|
||||
<h2>Total Execution Hits: 1</h2>
|
||||
<h2>Function Coverage Overview: 11.11%</h2>
|
||||
<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
|
||||
<div class="collapse show" id="funcTable">
|
||||
<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">white_underline:2</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">white:6</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">green:10</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">red:14</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">yellow:18</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">red_highlight:22</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">green_highlight:26</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 18ch;">gray:30</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
</tbody></table></div>
|
||||
<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
|
||||
<tr><td>1</td><td>1</td><td><span class=high-hits>return {</span></td></tr>
|
||||
<tr><td>2</td><td>1</td><td><span class=high-hits>white_underline = function(s: any)</span></td></tr>
|
||||
<tr><td>3</td><td>0</td><td><span class=zero-hits>return `\27[1;4m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>4</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>6</td><td>1</td><td><span class=high-hits>white = function(s: any)</span></td></tr>
|
||||
<tr><td>7</td><td>0</td><td><span class=zero-hits>return `\27[37;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>8</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>10</td><td>1</td><td><span class=high-hits>green = function(s: any)</span></td></tr>
|
||||
<tr><td>11</td><td>0</td><td><span class=zero-hits>return `\27[32;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>12</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>14</td><td>1</td><td><span class=high-hits>red = function(s: any)</span></td></tr>
|
||||
<tr><td>15</td><td>0</td><td><span class=zero-hits>return `\27[31;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>16</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>18</td><td>1</td><td><span class=high-hits>yellow = function(s: any)</span></td></tr>
|
||||
<tr><td>19</td><td>0</td><td><span class=zero-hits>return `\27[33;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>21</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>22</td><td>1</td><td><span class=high-hits>red_highlight = function(s: any)</span></td></tr>
|
||||
<tr><td>23</td><td>0</td><td><span class=zero-hits>return `\27[41;1;30m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>24</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>26</td><td>1</td><td><span class=high-hits>green_highlight = function(s: any)</span></td></tr>
|
||||
<tr><td>27</td><td>0</td><td><span class=zero-hits>return `\27[42;1;30m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>28</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>29</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>30</td><td>1</td><td><span class=high-hits>gray = function(s: any)</span></td></tr>
|
||||
<tr><td>31</td><td>0</td><td><span class=zero-hits>return `\27[30;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>32</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>33</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
</tbody></table></body></html>
|
||||
74
docs/public/coverage/entity_visualiser.luau.html
vendored
74
docs/public/coverage/entity_visualiser.luau.html
vendored
|
|
@ -1,74 +0,0 @@
|
|||
<html><head>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
|
||||
<style>
|
||||
body { font-family: monospace; text-align: center; }
|
||||
#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
|
||||
#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
|
||||
#funcTable th { background-color: #ddd; }
|
||||
#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
|
||||
.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
|
||||
.nonzero-hits { color: green; font-weight: bold; }
|
||||
.low-hits { background-color: #ffe6b3; }
|
||||
.high-hits { background-color: #cfc; }
|
||||
.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
|
||||
table.table { font-size: 14px; border-collapse: collapse; }
|
||||
table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
|
||||
table.table tr { height: auto; }
|
||||
</style></head><body>
|
||||
<h1 class="text-center">entity_visualiser.luau Coverage</h1>
|
||||
<h2>Total Execution Hits: 1</h2>
|
||||
<h2>Function Coverage Overview: 25.00%</h2>
|
||||
<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
|
||||
<div class="collapse show" id="funcTable">
|
||||
<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
|
||||
<tr><td style="padding: 1px; min-width: 13ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 13ch;">pe:6</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 13ch;">name:11</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 13ch;">components:15</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
</tbody></table></div>
|
||||
<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
|
||||
<tr><td>1</td><td>1</td><td><span class=high-hits>local jecs = require("@jecs")</span></td></tr>
|
||||
<tr><td>2</td><td>1</td><td><span class=high-hits>local ECS_GENERATION = jecs.ECS_GENERATION</span></td></tr>
|
||||
<tr><td>3</td><td>1</td><td><span class=high-hits>local ECS_ID = jecs.ECS_ID</span></td></tr>
|
||||
<tr><td>4</td><td>1</td><td><span class=high-hits>local ansi = require("@tools/ansi")</span></td></tr>
|
||||
<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>6</td><td>1</td><td><span class=high-hits>local function pe(e: any)</span></td></tr>
|
||||
<tr><td>7</td><td>0</td><td><span class=zero-hits>local gen = ECS_GENERATION(e)</span></td></tr>
|
||||
<tr><td>8</td><td>0</td><td><span class=zero-hits>return ansi.green(`e{ECS_ID(e)}`) .. ansi.yellow(`v{gen}`)</span></td></tr>
|
||||
<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>10</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>11</td><td>1</td><td><span class=high-hits>local function name(world: jecs.World, id: any)</span></td></tr>
|
||||
<tr><td>12</td><td>0</td><td><span class=zero-hits>return world:get(id, jecs.Name) or `${id}`</span></td></tr>
|
||||
<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>14</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>15</td><td>1</td><td><span class=high-hits>local function components(world: jecs.World, entity: any)</span></td></tr>
|
||||
<tr><td>16</td><td>0</td><td><span class=zero-hits>local r = jecs.entity_index_try_get(world.entity_index, entity)</span></td></tr>
|
||||
<tr><td>17</td><td>0</td><td><span class=zero-hits>if not r then</span></td></tr>
|
||||
<tr><td>18</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>19</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>21</td><td>0</td><td><span class=zero-hits>local archetype = r.archetype</span></td></tr>
|
||||
<tr><td>22</td><td>0</td><td><span class=zero-hits>local row = r.row</span></td></tr>
|
||||
<tr><td>23</td><td>0</td><td><span class=zero-hits>print(`Entity {pe(entity)}`)</span></td></tr>
|
||||
<tr><td>24</td><td>0</td><td><span class=zero-hits>print("-----------------------------------------------------")</span></td></tr>
|
||||
<tr><td>25</td><td>0</td><td><span class=zero-hits>for i, column in archetype.columns do</span></td></tr>
|
||||
<tr><td>26</td><td>0</td><td><span class=zero-hits>local component = archetype.types[i]</span></td></tr>
|
||||
<tr><td>27</td><td>0</td><td><span class=zero-hits>local n</span></td></tr>
|
||||
<tr><td>28</td><td>0</td><td><span class=zero-hits>if jecs.IS_PAIR(component) then</span></td></tr>
|
||||
<tr><td>29</td><td>0</td><td><span class=zero-hits>n = `({name(world, jecs.pair_first(world, component))}, {name(world, jecs.pair_second(world, component))})`</span></td></tr>
|
||||
<tr><td>30</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>31</td><td>0</td><td><span class=zero-hits>n = name(world, component)</span></td></tr>
|
||||
<tr><td>32</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>33</td><td>0</td><td><span class=zero-hits>local data = column[row] or "TAG"</span></td></tr>
|
||||
<tr><td>34</td><td>0</td><td><span class=zero-hits>print(`| {n} | {data} |`)</span></td></tr>
|
||||
<tr><td>35</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>36</td><td>0</td><td><span class=zero-hits>print("-----------------------------------------------------")</span></td></tr>
|
||||
<tr><td>37</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
|
||||
<tr><td>38</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>39</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>40</td><td>1</td><td><span class=high-hits>return {</span></td></tr>
|
||||
<tr><td>41</td><td>1</td><td><span class=high-hits>components = components,</span></td></tr>
|
||||
<tr><td>42</td><td>1</td><td><span class=high-hits>prettify = pe,</span></td></tr>
|
||||
<tr><td>43</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
</tbody></table></body></html>
|
||||
12
docs/public/coverage/index.html
vendored
12
docs/public/coverage/index.html
vendored
|
|
@ -1,12 +0,0 @@
|
|||
<html><head>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
|
||||
</head><body>
|
||||
<h1 class="text-center">Coverage Report</h1>
|
||||
<table class="table table-striped table-bordered"><thead><tr><th>File</th><th>Total Hits</th><th>Functions</th></tr></thead><tbody>
|
||||
<tr><td><a href="tests.luau.html">tests.luau</a></td><td>100</td><td>67</td></tr>
|
||||
<tr><td><a href="jecs.luau.html">jecs.luau</a></td><td>1006447</td><td>97</td></tr>
|
||||
<tr><td><a href="testkit.luau.html">testkit.luau</a></td><td>1826</td><td>31</td></tr>
|
||||
<tr><td><a href="lifetime_tracker.luau.html">lifetime_tracker.luau</a></td><td>1</td><td>11</td></tr>
|
||||
<tr><td><a href="entity_visualiser.luau.html">entity_visualiser.luau</a></td><td>1</td><td>4</td></tr>
|
||||
<tr><td><a href="ansi.luau.html">ansi.luau</a></td><td>1</td><td>9</td></tr>
|
||||
</tbody></table></body></html>
|
||||
2798
docs/public/coverage/jecs.luau.html
vendored
2798
docs/public/coverage/jecs.luau.html
vendored
File diff suppressed because it is too large
Load diff
254
docs/public/coverage/lifetime_tracker.luau.html
vendored
254
docs/public/coverage/lifetime_tracker.luau.html
vendored
|
|
@ -1,254 +0,0 @@
|
|||
<html><head>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
|
||||
<style>
|
||||
body { font-family: monospace; text-align: center; }
|
||||
#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
|
||||
#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
|
||||
#funcTable th { background-color: #ddd; }
|
||||
#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
|
||||
.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
|
||||
.nonzero-hits { color: green; font-weight: bold; }
|
||||
.low-hits { background-color: #ffe6b3; }
|
||||
.high-hits { background-color: #cfc; }
|
||||
.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
|
||||
table.table { font-size: 14px; border-collapse: collapse; }
|
||||
table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
|
||||
table.table tr { height: auto; }
|
||||
</style></head><body>
|
||||
<h1 class="text-center">lifetime_tracker.luau Coverage</h1>
|
||||
<h2>Total Execution Hits: 1</h2>
|
||||
<h2>Function Coverage Overview: 9.09%</h2>
|
||||
<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
|
||||
<div class="collapse show" id="funcTable">
|
||||
<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;">print_centered_entity:12</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;">name:26</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;">pad:30</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;">lifetime_tracker_add:36</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:48</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:62</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:89</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:135</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:164</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 24ch;"><anonymous>:175</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
</tbody></table></div>
|
||||
<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
|
||||
<tr><td>1</td><td>1</td><td><span class=high-hits>local jecs = require("@jecs")</span></td></tr>
|
||||
<tr><td>2</td><td>1</td><td><span class=high-hits>local ECS_GENERATION = jecs.ECS_GENERATION</span></td></tr>
|
||||
<tr><td>3</td><td>1</td><td><span class=high-hits>local ECS_ID = jecs.ECS_ID</span></td></tr>
|
||||
<tr><td>4</td><td>1</td><td><span class=high-hits>local __ = jecs.Wildcard</span></td></tr>
|
||||
<tr><td>5</td><td>1</td><td><span class=high-hits>local pair = jecs.pair</span></td></tr>
|
||||
<tr><td>6</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>7</td><td>1</td><td><span class=high-hits>local prettify = require("@tools/entity_visualiser").prettify</span></td></tr>
|
||||
<tr><td>8</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>9</td><td>1</td><td><span class=high-hits>local pe = prettify</span></td></tr>
|
||||
<tr><td>10</td><td>1</td><td><span class=high-hits>local ansi = require("@tools/ansi")</span></td></tr>
|
||||
<tr><td>11</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>12</td><td>1</td><td><span class=high-hits>function print_centered_entity(entity, width: number)</span></td></tr>
|
||||
<tr><td>13</td><td>0</td><td><span class=zero-hits>local entity_str = tostring(entity)</span></td></tr>
|
||||
<tr><td>14</td><td>0</td><td><span class=zero-hits>local entity_length = #entity_str</span></td></tr>
|
||||
<tr><td>15</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>16</td><td>0</td><td><span class=zero-hits>local padding_total = width - 2 - entity_length</span></td></tr>
|
||||
<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>18</td><td>0</td><td><span class=zero-hits>local padding_left = math.floor(padding_total / 2)</span></td></tr>
|
||||
<tr><td>19</td><td>0</td><td><span class=zero-hits>local padding_right = padding_total - padding_left</span></td></tr>
|
||||
<tr><td>20</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>21</td><td>0</td><td><span class=zero-hits>local centered_str = string.rep(" ", padding_left) .. entity_str .. string.rep(" ", padding_right)</span></td></tr>
|
||||
<tr><td>22</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>23</td><td>0</td><td><span class=zero-hits>print("|" .. centered_str .. "|")</span></td></tr>
|
||||
<tr><td>24</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>26</td><td>1</td><td><span class=high-hits>local function name(world, e)</span></td></tr>
|
||||
<tr><td>27</td><td>0</td><td><span class=zero-hits>return world:get(world, e, jecs.Name) or pe(e)</span></td></tr>
|
||||
<tr><td>28</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>29</td><td>1</td><td><span class=high-hits>local padding_enabled = false</span></td></tr>
|
||||
<tr><td>30</td><td>1</td><td><span class=high-hits>local function pad()</span></td></tr>
|
||||
<tr><td>31</td><td>0</td><td><span class=zero-hits>if padding_enabled then</span></td></tr>
|
||||
<tr><td>32</td><td>0</td><td><span class=zero-hits>print("")</span></td></tr>
|
||||
<tr><td>33</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>34</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>35</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>36</td><td>1</td><td><span class=high-hits>local function lifetime_tracker_add(world: jecs.World, opt)</span></td></tr>
|
||||
<tr><td>37</td><td>0</td><td><span class=zero-hits>local entity_index = world.entity_index</span></td></tr>
|
||||
<tr><td>38</td><td>0</td><td><span class=zero-hits>local dense_array = entity_index.dense_array</span></td></tr>
|
||||
<tr><td>39</td><td>0</td><td><span class=zero-hits>local component_index = world.component_index</span></td></tr>
|
||||
<tr><td>40</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>41</td><td>0</td><td><span class=zero-hits>local ENTITY_RANGE = (jecs.Rest :: any) + 1</span></td></tr>
|
||||
<tr><td>42</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>43</td><td>0</td><td><span class=zero-hits>local w = setmetatable({}, { __index = world })</span></td></tr>
|
||||
<tr><td>44</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>45</td><td>0</td><td><span class=zero-hits>padding_enabled = opt.padding_enabled</span></td></tr>
|
||||
<tr><td>46</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>47</td><td>0</td><td><span class=zero-hits>local world_entity = world.entity</span></td></tr>
|
||||
<tr><td>48</td><td>0</td><td><span class=zero-hits>w.entity = function(self, entity)</span></td></tr>
|
||||
<tr><td>49</td><td>0</td><td><span class=zero-hits>if entity then</span></td></tr>
|
||||
<tr><td>50</td><td>0</td><td><span class=zero-hits>return world_entity(world, entity)</span></td></tr>
|
||||
<tr><td>51</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>52</td><td>0</td><td><span class=zero-hits>local will_recycle = entity_index.max_id ~= entity_index.alive_count</span></td></tr>
|
||||
<tr><td>53</td><td>0</td><td><span class=zero-hits>local e = world_entity(world)</span></td></tr>
|
||||
<tr><td>54</td><td>0</td><td><span class=zero-hits>if will_recycle then</span></td></tr>
|
||||
<tr><td>55</td><td>0</td><td><span class=zero-hits>print(`*recycled {pe(e)}`)</span></td></tr>
|
||||
<tr><td>56</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>57</td><td>0</td><td><span class=zero-hits>print(`*created {pe(e)}`)</span></td></tr>
|
||||
<tr><td>58</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>59</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>60</td><td>0</td><td><span class=zero-hits>return e</span></td></tr>
|
||||
<tr><td>61</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>62</td><td>0</td><td><span class=zero-hits>w.print_entity_index = function(self)</span></td></tr>
|
||||
<tr><td>63</td><td>0</td><td><span class=zero-hits>local max_id = entity_index.max_id</span></td></tr>
|
||||
<tr><td>64</td><td>0</td><td><span class=zero-hits>local alive_count = entity_index.alive_count</span></td></tr>
|
||||
<tr><td>65</td><td>0</td><td><span class=zero-hits>local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})</span></td></tr>
|
||||
<tr><td>66</td><td>0</td><td><span class=zero-hits>local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})</span></td></tr>
|
||||
<tr><td>67</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>68</td><td>0</td><td><span class=zero-hits>local sep = "|--------|"</span></td></tr>
|
||||
<tr><td>69</td><td>0</td><td><span class=zero-hits>if #alive > 0 then</span></td></tr>
|
||||
<tr><td>70</td><td>0</td><td><span class=zero-hits>print("|-alive--|")</span></td></tr>
|
||||
<tr><td>71</td><td>0</td><td><span class=zero-hits>for i = 1, #alive do</span></td></tr>
|
||||
<tr><td>72</td><td>0</td><td><span class=zero-hits>local e = pe(alive[i])</span></td></tr>
|
||||
<tr><td>73</td><td>0</td><td><span class=zero-hits>print_centered_entity(e, 32)</span></td></tr>
|
||||
<tr><td>74</td><td>0</td><td><span class=zero-hits>print(sep)</span></td></tr>
|
||||
<tr><td>75</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>76</td><td>0</td><td><span class=zero-hits>print("\n")</span></td></tr>
|
||||
<tr><td>77</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>78</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>79</td><td>0</td><td><span class=zero-hits>if #dead > 0 then</span></td></tr>
|
||||
<tr><td>80</td><td>0</td><td><span class=zero-hits>print("|--dead--|")</span></td></tr>
|
||||
<tr><td>81</td><td>0</td><td><span class=zero-hits>for i = 1, #dead do</span></td></tr>
|
||||
<tr><td>82</td><td>0</td><td><span class=zero-hits>print_centered_entity(pe(dead[i]), 32)</span></td></tr>
|
||||
<tr><td>83</td><td>0</td><td><span class=zero-hits>print(sep)</span></td></tr>
|
||||
<tr><td>84</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>85</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>86</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>87</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>88</td><td>0</td><td><span class=zero-hits>local timelines = {}</span></td></tr>
|
||||
<tr><td>89</td><td>0</td><td><span class=zero-hits>w.print_snapshot = function(self)</span></td></tr>
|
||||
<tr><td>90</td><td>0</td><td><span class=zero-hits>local timeline = #timelines + 1</span></td></tr>
|
||||
<tr><td>91</td><td>0</td><td><span class=zero-hits>local entity_column_width = 10</span></td></tr>
|
||||
<tr><td>92</td><td>0</td><td><span class=zero-hits>local status_column_width = 8</span></td></tr>
|
||||
<tr><td>93</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>94</td><td>0</td><td><span class=zero-hits>local header = string.format("| %-" .. entity_column_width .. "s |", "Entity")</span></td></tr>
|
||||
<tr><td>95</td><td>0</td><td><span class=zero-hits>for i = 1, timeline do</span></td></tr>
|
||||
<tr><td>96</td><td>0</td><td><span class=zero-hits>header = header .. string.format(" %-" .. status_column_width .. "s |", string.format("T%d", i))</span></td></tr>
|
||||
<tr><td>97</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>98</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>99</td><td>0</td><td><span class=zero-hits>local max_id = entity_index.max_id</span></td></tr>
|
||||
<tr><td>100</td><td>0</td><td><span class=zero-hits>local alive_count = entity_index.alive_count</span></td></tr>
|
||||
<tr><td>101</td><td>0</td><td><span class=zero-hits>local alive = table.move(dense_array, 1 + jecs.Rest :: any, alive_count, 1, {})</span></td></tr>
|
||||
<tr><td>102</td><td>0</td><td><span class=zero-hits>local dead = table.move(dense_array, alive_count + 1, max_id, 1, {})</span></td></tr>
|
||||
<tr><td>103</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>104</td><td>0</td><td><span class=zero-hits>local data = {}</span></td></tr>
|
||||
<tr><td>105</td><td>0</td><td><span class=zero-hits>print("-------------------------------------------------------------------")</span></td></tr>
|
||||
<tr><td>106</td><td>0</td><td><span class=zero-hits>print(header)</span></td></tr>
|
||||
<tr><td>107</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>108</td><td><span class='text-muted'>N/A</span></td><td>-- Store the snapshot data for this timeline</td>></tr>
|
||||
<tr><td>109</td><td>0</td><td><span class=zero-hits>for i = ENTITY_RANGE, max_id do</span></td></tr>
|
||||
<tr><td>110</td><td>0</td><td><span class=zero-hits>if dense_array[i] then</span></td></tr>
|
||||
<tr><td>111</td><td>0</td><td><span class=zero-hits>local entity = dense_array[i]</span></td></tr>
|
||||
<tr><td>112</td><td>0</td><td><span class=zero-hits>local id = ECS_ID(entity)</span></td></tr>
|
||||
<tr><td>113</td><td>0</td><td><span class=zero-hits>local status = "alive"</span></td></tr>
|
||||
<tr><td>114</td><td>0</td><td><span class=zero-hits>if not world:contains(entity) then</span></td></tr>
|
||||
<tr><td>115</td><td>0</td><td><span class=zero-hits>status = "dead"</span></td></tr>
|
||||
<tr><td>116</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>117</td><td>0</td><td><span class=zero-hits>data[id] = status</span></td></tr>
|
||||
<tr><td>118</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>119</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>120</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>121</td><td>0</td><td><span class=zero-hits>table.insert(timelines, data)</span></td></tr>
|
||||
<tr><td>122</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>123</td><td><span class='text-muted'>N/A</span></td><td>-- Create a table to hold entity data for sorting</td>></tr>
|
||||
<tr><td>124</td><td>0</td><td><span class=zero-hits>local entities = {}</span></td></tr>
|
||||
<tr><td>125</td><td>0</td><td><span class=zero-hits>for i = ENTITY_RANGE, max_id do</span></td></tr>
|
||||
<tr><td>126</td><td>0</td><td><span class=zero-hits>if dense_array[i] then</span></td></tr>
|
||||
<tr><td>127</td><td>0</td><td><span class=zero-hits>local entity = dense_array[i]</span></td></tr>
|
||||
<tr><td>128</td><td>0</td><td><span class=zero-hits>local id = ECS_ID(entity)</span></td></tr>
|
||||
<tr><td>129</td><td><span class='text-muted'>N/A</span></td><td>-- Push entity and id into the new `entities` table</td>></tr>
|
||||
<tr><td>130</td><td>0</td><td><span class=zero-hits>table.insert(entities, { entity = entity, id = id })</span></td></tr>
|
||||
<tr><td>131</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>132</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>133</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>134</td><td><span class='text-muted'>N/A</span></td><td>-- Sort the entities by ECS_ID</td>></tr>
|
||||
<tr><td>135</td><td>0</td><td><span class=zero-hits>table.sort(entities, function(a, b)</span></td></tr>
|
||||
<tr><td>136</td><td>0</td><td><span class=zero-hits>return a.id < b.id</span></td></tr>
|
||||
<tr><td>137</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
|
||||
<tr><td>138</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>139</td><td><span class='text-muted'>N/A</span></td><td>-- Print the sorted rows</td>></tr>
|
||||
<tr><td>140</td><td>0</td><td><span class=zero-hits>for _, entity_data in ipairs(entities) do</span></td></tr>
|
||||
<tr><td>141</td><td>0</td><td><span class=zero-hits>local entity = entity_data.entity</span></td></tr>
|
||||
<tr><td>142</td><td>0</td><td><span class=zero-hits>local id = entity_data.id</span></td></tr>
|
||||
<tr><td>143</td><td>0</td><td><span class=zero-hits>local status = "alive"</span></td></tr>
|
||||
<tr><td>144</td><td>0</td><td><span class=zero-hits>if id > alive_count then</span></td></tr>
|
||||
<tr><td>145</td><td>0</td><td><span class=zero-hits>status = "dead"</span></td></tr>
|
||||
<tr><td>146</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>147</td><td>0</td><td><span class=zero-hits>local row = string.format("| %-" .. entity_column_width .. "s |", pe(entity))</span></td></tr>
|
||||
<tr><td>148</td><td>0</td><td><span class=zero-hits>for j = 1, timeline do</span></td></tr>
|
||||
<tr><td>149</td><td>0</td><td><span class=zero-hits>local timeline_data = timelines[j]</span></td></tr>
|
||||
<tr><td>150</td><td>0</td><td><span class=zero-hits>local entity_data = timeline_data[id]</span></td></tr>
|
||||
<tr><td>151</td><td>0</td><td><span class=zero-hits>if entity_data then</span></td></tr>
|
||||
<tr><td>152</td><td>0</td><td><span class=zero-hits>row = row .. string.format(" %-" .. status_column_width .. "s |", entity_data)</span></td></tr>
|
||||
<tr><td>153</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>154</td><td>0</td><td><span class=zero-hits>row = row .. string.format(" %-" .. status_column_width .. "s |", "-")</span></td></tr>
|
||||
<tr><td>155</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>156</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>157</td><td>0</td><td><span class=zero-hits>print(row)</span></td></tr>
|
||||
<tr><td>158</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>159</td><td>0</td><td><span class=zero-hits>print("-------------------------------------------------------------------")</span></td></tr>
|
||||
<tr><td>160</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>161</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>162</td><td>0</td><td><span class=zero-hits>local world_add = world.add</span></td></tr>
|
||||
<tr><td>163</td><td>0</td><td><span class=zero-hits>local relations = {}</span></td></tr>
|
||||
<tr><td>164</td><td>0</td><td><span class=zero-hits>w.add = function(self, entity: any, component: any)</span></td></tr>
|
||||
<tr><td>165</td><td>0</td><td><span class=zero-hits>world_add(world, entity, component)</span></td></tr>
|
||||
<tr><td>166</td><td>0</td><td><span class=zero-hits>if jecs.IS_PAIR(component) then</span></td></tr>
|
||||
<tr><td>167</td><td>0</td><td><span class=zero-hits>local relation = jecs.pair_first(world, component)</span></td></tr>
|
||||
<tr><td>168</td><td>0</td><td><span class=zero-hits>local target = jecs.pair_second(world, component)</span></td></tr>
|
||||
<tr><td>169</td><td>0</td><td><span class=zero-hits>print(`*added ({pe(relation)}, {pe(target)}) to {pe(entity)}`)</span></td></tr>
|
||||
<tr><td>170</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>171</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>172</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>173</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>174</td><td>0</td><td><span class=zero-hits>local world_delete = world.delete</span></td></tr>
|
||||
<tr><td>175</td><td>0</td><td><span class=zero-hits>w.delete = function(self, e)</span></td></tr>
|
||||
<tr><td>176</td><td>0</td><td><span class=zero-hits>world_delete(world, e)</span></td></tr>
|
||||
<tr><td>177</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>178</td><td>0</td><td><span class=zero-hits>local idr_t = component_index[pair(__, e)]</span></td></tr>
|
||||
<tr><td>179</td><td>0</td><td><span class=zero-hits>if idr_t then</span></td></tr>
|
||||
<tr><td>180</td><td>0</td><td><span class=zero-hits>for archetype_id in idr_t.cache do</span></td></tr>
|
||||
<tr><td>181</td><td>0</td><td><span class=zero-hits>local archetype = world.archetypes[archetype_id]</span></td></tr>
|
||||
<tr><td>182</td><td>0</td><td><span class=zero-hits>for _, id in archetype.types do</span></td></tr>
|
||||
<tr><td>183</td><td>0</td><td><span class=zero-hits>if not jecs.IS_PAIR(id) then</span></td></tr>
|
||||
<tr><td>184</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
|
||||
<tr><td>185</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>186</td><td>0</td><td><span class=zero-hits>local object = jecs.pair_second(world, id)</span></td></tr>
|
||||
<tr><td>187</td><td>0</td><td><span class=zero-hits>if object ~= e then</span></td></tr>
|
||||
<tr><td>188</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
|
||||
<tr><td>189</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>190</td><td>0</td><td><span class=zero-hits>local id_record = component_index[id]</span></td></tr>
|
||||
<tr><td>191</td><td>0</td><td><span class=zero-hits>local flags = id_record.flags</span></td></tr>
|
||||
<tr><td>192</td><td>0</td><td><span class=zero-hits>local flags_delete_mask: number = bit32.band(flags, jecs.ECS_ID_DELETE)</span></td></tr>
|
||||
<tr><td>193</td><td>0</td><td><span class=zero-hits>if flags_delete_mask ~= 0 then</span></td></tr>
|
||||
<tr><td>194</td><td>0</td><td><span class=zero-hits>for _, entity in archetype.entities do</span></td></tr>
|
||||
<tr><td>195</td><td>0</td><td><span class=zero-hits>print(`*deleted dependant {pe(entity)} of {pe(e)}`)</span></td></tr>
|
||||
<tr><td>196</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>197</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>198</td><td>0</td><td><span class=zero-hits>break</span></td></tr>
|
||||
<tr><td>199</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>200</td><td>0</td><td><span class=zero-hits>for _, entity in archetype.entities do</span></td></tr>
|
||||
<tr><td>201</td><td>0</td><td><span class=zero-hits>print(</span></td></tr>
|
||||
<tr><td>202</td><td>0</td><td><span class=zero-hits>`*removed dependency ({pe(jecs.pair_first(world, id))}, {pe(object)}) from {pe(entity)}`</span></td></tr>
|
||||
<tr><td>203</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
|
||||
<tr><td>204</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>205</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>206</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>207</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>208</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>209</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>210</td><td>0</td><td><span class=zero-hits>print(`*deleted {pe(e)}`)</span></td></tr>
|
||||
<tr><td>211</td><td>0</td><td><span class=zero-hits>pad()</span></td></tr>
|
||||
<tr><td>212</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>213</td><td>0</td><td><span class=zero-hits>return w</span></td></tr>
|
||||
<tr><td>214</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>215</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>216</td><td>1</td><td><span class=high-hits>return lifetime_tracker_add</span></td></tr>
|
||||
</tbody></table></body></html>
|
||||
617
docs/public/coverage/testkit.luau.html
vendored
617
docs/public/coverage/testkit.luau.html
vendored
|
|
@ -1,617 +0,0 @@
|
|||
<html><head>
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/css/bootstrap.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.0/js/bootstrap.bundle.min.js"></script>
|
||||
<style>
|
||||
body { font-family: monospace; text-align: center; }
|
||||
#funcTable table { margin: 0 auto; width: auto; max-width: 300px; font-size: 14px; border-collapse: collapse; }
|
||||
#funcTable th, #funcTable td { padding: 2px 6px; text-align: left; white-space: nowrap; }
|
||||
#funcTable th { background-color: #ddd; }
|
||||
#funcTable td:nth-child(2) { text-align: right; min-width: 50px; }
|
||||
.zero-hits { background-color: #fcc; font-weight: bold; color: red; }
|
||||
.nonzero-hits { color: green; font-weight: bold; }
|
||||
.low-hits { background-color: #ffe6b3; }
|
||||
.high-hits { background-color: #cfc; }
|
||||
.source-code-table { margin-left: 10px; }th, td { padding: 0px; font-size: 12px; }
|
||||
table.table { font-size: 14px; border-collapse: collapse; }
|
||||
table.table th, table.table td { padding: 1px; font-size: 12px; line-height: 1.2; }
|
||||
table.table tr { height: auto; }
|
||||
</style></head><body>
|
||||
<h1 class="text-center">testkit.luau Coverage</h1>
|
||||
<h2>Total Execution Hits: 1826</h2>
|
||||
<h2>Function Coverage Overview: 64.52%</h2>
|
||||
<button class="btn btn-primary mb-2" type="button" data-bs-toggle="collapse" data-bs-target="#funcTable">Toggle Function Coverage</button>
|
||||
<div class="collapse show" id="funcTable">
|
||||
<h2>Function Coverage:</h2><table class="table table-bordered"><thead><tr><th>Function</th><th>Hits</th></tr></thead><tbody>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;"><main></td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">white_underline:11</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">white:15</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">green:19</td><td style="padding: 1px; color: green; font-weight: bold;">77</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">red:23</td><td style="padding: 1px; color: green; font-weight: bold;">146</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">yellow:27</td><td style="padding: 1px; color: green; font-weight: bold;">76</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">red_highlight:31</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">green_highlight:35</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">gray:39</td><td style="padding: 1px; color: green; font-weight: bold;">84</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">orange:43</td><td style="padding: 1px; color: green; font-weight: bold;">73</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">convert_units:48</td><td style="padding: 1px; color: green; font-weight: bold;">6</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">output_test_result:131</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">CASE:169</td><td style="padding: 1px; color: green; font-weight: bold;">73</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">CHECK_EXPECT_ERR:183</td><td style="padding: 1px; color: green; font-weight: bold;">9</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">CHECK:201</td><td style="padding: 1px; color: green; font-weight: bold;">1195</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">TEST:224</td><td style="padding: 1px; color: green; font-weight: bold;">24</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">FOCUS:237</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">FINISH:248</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;"><anonymous>:264</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">SKIP:314</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">START:330</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">BENCH:342</td><td style="padding: 1px; color: green; font-weight: bold;">3</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;"><anonymous>:354</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">round:372</td><td style="padding: 1px; color: green; font-weight: bold;">6</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">print2:396</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">tos:401</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">shallow_eq:480</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">deep_eq:500</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">test:533</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">benchmark:545</td><td style="padding: 1px; color: green; font-weight: bold;">1</td></tr>
|
||||
<tr><td style="padding: 1px; min-width: 22ch;">disable_formatting:549</td><td style="padding: 1px; color: red; font-weight: bold;">0</td></tr>
|
||||
</tbody></table></div>
|
||||
<h2>Source Code:</h2><table class="table table-bordered source-code-table "><thead><tr><th>Line</th><th>Hits</th><th>Code</th></tr></thead><tbody>
|
||||
<tr><td>1</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>2</td><td><span class='text-muted'>N/A</span></td><td>-- testkit.luau</td>></tr>
|
||||
<tr><td>3</td><td><span class='text-muted'>N/A</span></td><td>-- v0.7.3</td>></tr>
|
||||
<tr><td>4</td><td><span class='text-muted'>N/A</span></td><td>-- MIT License</td>></tr>
|
||||
<tr><td>5</td><td><span class='text-muted'>N/A</span></td><td>-- Copyright (c) 2022 centau</td>></tr>
|
||||
<tr><td>6</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>7</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>8</td><td>1</td><td><span class=low-hits>local disable_ansi = false</span></td></tr>
|
||||
<tr><td>9</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>10</td><td>1</td><td><span class=low-hits>local color = {</span></td></tr>
|
||||
<tr><td>11</td><td>1</td><td><span class=low-hits>white_underline = function(s: string): string</span></td></tr>
|
||||
<tr><td>12</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[1;4m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>13</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>14</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>15</td><td>1</td><td><span class=low-hits>white = function(s: string): string</span></td></tr>
|
||||
<tr><td>16</td><td>24</td><td><span class=low-hits>return if disable_ansi then s else `\27[37;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>17</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>18</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>19</td><td>1</td><td><span class=low-hits>green = function(s: string): string</span></td></tr>
|
||||
<tr><td>20</td><td>77</td><td><span class=low-hits>return if disable_ansi then s else `\27[32;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>21</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>22</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>23</td><td>1</td><td><span class=low-hits>red = function(s: string): string</span></td></tr>
|
||||
<tr><td>24</td><td>146</td><td><span class=low-hits>return if disable_ansi then s else `\27[31;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>25</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>26</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>27</td><td>1</td><td><span class=low-hits>yellow = function(s: string): string</span></td></tr>
|
||||
<tr><td>28</td><td>76</td><td><span class=low-hits>return if disable_ansi then s else `\27[33;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>29</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>30</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>31</td><td>1</td><td><span class=low-hits>red_highlight = function(s: string): string</span></td></tr>
|
||||
<tr><td>32</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[41;1;30m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>33</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>34</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>35</td><td>1</td><td><span class=low-hits>green_highlight = function(s: string): string</span></td></tr>
|
||||
<tr><td>36</td><td>0</td><td><span class=zero-hits>return if disable_ansi then s else `\27[42;1;30m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>37</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>38</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>39</td><td>1</td><td><span class=low-hits>gray = function(s: string): string</span></td></tr>
|
||||
<tr><td>40</td><td>84</td><td><span class=low-hits>return if disable_ansi then s else `\27[38;1m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>41</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>42</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>43</td><td>1</td><td><span class=low-hits>orange = function(s: string): string</span></td></tr>
|
||||
<tr><td>44</td><td>73</td><td><span class=low-hits>return if disable_ansi then s else `\27[38;5;208m{s}\27[0m`</span></td></tr>
|
||||
<tr><td>45</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>46</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>47</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>48</td><td>1</td><td><span class=low-hits>local function convert_units(unit: string, value: number): (number, string)</span></td></tr>
|
||||
<tr><td>49</td><td>6</td><td><span class=low-hits>local sign = math.sign(value)</span></td></tr>
|
||||
<tr><td>50</td><td>6</td><td><span class=low-hits>value = math.abs(value)</span></td></tr>
|
||||
<tr><td>51</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>52</td><td>6</td><td><span class=low-hits>local prefix_colors = {</span></td></tr>
|
||||
<tr><td>53</td><td>6</td><td><span class=low-hits>[4] = color.red,</span></td></tr>
|
||||
<tr><td>54</td><td>6</td><td><span class=low-hits>[3] = color.red,</span></td></tr>
|
||||
<tr><td>55</td><td>6</td><td><span class=low-hits>[2] = color.yellow,</span></td></tr>
|
||||
<tr><td>56</td><td>6</td><td><span class=low-hits>[1] = color.yellow,</span></td></tr>
|
||||
<tr><td>57</td><td>6</td><td><span class=low-hits>[0] = color.green,</span></td></tr>
|
||||
<tr><td>58</td><td>6</td><td><span class=low-hits>[-1] = color.red,</span></td></tr>
|
||||
<tr><td>59</td><td>6</td><td><span class=low-hits>[-2] = color.yellow,</span></td></tr>
|
||||
<tr><td>60</td><td>6</td><td><span class=low-hits>[-3] = color.green,</span></td></tr>
|
||||
<tr><td>61</td><td>6</td><td><span class=low-hits>[-4] = color.red,</span></td></tr>
|
||||
<tr><td>62</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>63</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>64</td><td>6</td><td><span class=low-hits>local prefixes = {</span></td></tr>
|
||||
<tr><td>65</td><td>6</td><td><span class=low-hits>[4] = "T",</span></td></tr>
|
||||
<tr><td>66</td><td>6</td><td><span class=low-hits>[3] = "G",</span></td></tr>
|
||||
<tr><td>67</td><td>6</td><td><span class=low-hits>[2] = "M",</span></td></tr>
|
||||
<tr><td>68</td><td>6</td><td><span class=low-hits>[1] = "k",</span></td></tr>
|
||||
<tr><td>69</td><td>6</td><td><span class=low-hits>[0] = " ",</span></td></tr>
|
||||
<tr><td>70</td><td>6</td><td><span class=low-hits>[-1] = "m",</span></td></tr>
|
||||
<tr><td>71</td><td>6</td><td><span class=low-hits>[-2] = "u",</span></td></tr>
|
||||
<tr><td>72</td><td>6</td><td><span class=low-hits>[-3] = "n",</span></td></tr>
|
||||
<tr><td>73</td><td>6</td><td><span class=low-hits>[-4] = "p",</span></td></tr>
|
||||
<tr><td>74</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>75</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>76</td><td>6</td><td><span class=low-hits>local order = 0</span></td></tr>
|
||||
<tr><td>77</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>78</td><td>7</td><td><span class=low-hits>while value >= 1000 do</span></td></tr>
|
||||
<tr><td>79</td><td>1</td><td><span class=low-hits>order += 1</span></td></tr>
|
||||
<tr><td>80</td><td>1</td><td><span class=low-hits>value /= 1000</span></td></tr>
|
||||
<tr><td>81</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>82</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>83</td><td>11</td><td><span class=low-hits>while value ~= 0 and value < 1 do</span></td></tr>
|
||||
<tr><td>84</td><td>7</td><td><span class=low-hits>order -= 1</span></td></tr>
|
||||
<tr><td>85</td><td>7</td><td><span class=low-hits>value *= 1000</span></td></tr>
|
||||
<tr><td>86</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>87</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>88</td><td>6</td><td><span class=low-hits>if value >= 100 then</span></td></tr>
|
||||
<tr><td>89</td><td>1</td><td><span class=low-hits>value = math.floor(value)</span></td></tr>
|
||||
<tr><td>90</td><td>5</td><td><span class=low-hits>elseif value >= 10 then</span></td></tr>
|
||||
<tr><td>91</td><td>2</td><td><span class=low-hits>value = math.floor(value * 1e1) / 1e1</span></td></tr>
|
||||
<tr><td>92</td><td>3</td><td><span class=low-hits>elseif value >= 1 then</span></td></tr>
|
||||
<tr><td>93</td><td>1</td><td><span class=low-hits>value = math.floor(value * 1e2) / 1e2</span></td></tr>
|
||||
<tr><td>94</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>95</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>96</td><td>6</td><td><span class=low-hits>return value * sign, prefix_colors[order](prefixes[order] .. unit)</span></td></tr>
|
||||
<tr><td>97</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>98</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>99</td><td>1</td><td><span class=low-hits>local WALL = color.gray("│")</span></td></tr>
|
||||
<tr><td>100</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>101</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>102</td><td><span class='text-muted'>N/A</span></td><td>-- Testing</td>></tr>
|
||||
<tr><td>103</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>104</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>105</td><td>0</td><td><span class=zero-hits>type Test = {</span></td></tr>
|
||||
<tr><td>106</td><td>0</td><td><span class=zero-hits>name: string,</span></td></tr>
|
||||
<tr><td>107</td><td>0</td><td><span class=zero-hits>case: Case?,</span></td></tr>
|
||||
<tr><td>108</td><td>0</td><td><span class=zero-hits>cases: { Case },</span></td></tr>
|
||||
<tr><td>109</td><td>0</td><td><span class=zero-hits>duration: number,</span></td></tr>
|
||||
<tr><td>110</td><td>0</td><td><span class=zero-hits>error: {</span></td></tr>
|
||||
<tr><td>111</td><td>0</td><td><span class=zero-hits>message: string,</span></td></tr>
|
||||
<tr><td>112</td><td>0</td><td><span class=zero-hits>trace: string,</span></td></tr>
|
||||
<tr><td>113</td><td>0</td><td><span class=zero-hits>}?,</span></td></tr>
|
||||
<tr><td>114</td><td>0</td><td><span class=zero-hits>focus: boolean,</span></td></tr>
|
||||
<tr><td>115</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>116</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>117</td><td>0</td><td><span class=zero-hits>type Case = {</span></td></tr>
|
||||
<tr><td>118</td><td>0</td><td><span class=zero-hits>name: string,</span></td></tr>
|
||||
<tr><td>119</td><td>0</td><td><span class=zero-hits>result: number,</span></td></tr>
|
||||
<tr><td>120</td><td>0</td><td><span class=zero-hits>line: number?,</span></td></tr>
|
||||
<tr><td>121</td><td>0</td><td><span class=zero-hits>focus: boolean,</span></td></tr>
|
||||
<tr><td>122</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>123</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>124</td><td>1</td><td><span class=low-hits>local PASS, FAIL, NONE, ERROR, SKIPPED = 1, 2, 3, 4, 5</span></td></tr>
|
||||
<tr><td>125</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>126</td><td>1</td><td><span class=low-hits>local check_for_focused = false</span></td></tr>
|
||||
<tr><td>127</td><td>1</td><td><span class=low-hits>local skip = false</span></td></tr>
|
||||
<tr><td>128</td><td>1</td><td><span class=low-hits>local test: Test?</span></td></tr>
|
||||
<tr><td>129</td><td>1</td><td><span class=low-hits>local tests: { Test } = {}</span></td></tr>
|
||||
<tr><td>130</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>131</td><td>1</td><td><span class=low-hits>local function output_test_result(test: Test)</span></td></tr>
|
||||
<tr><td>132</td><td>24</td><td><span class=low-hits>if check_for_focused then</span></td></tr>
|
||||
<tr><td>133</td><td>0</td><td><span class=zero-hits>local any_focused = test.focus</span></td></tr>
|
||||
<tr><td>134</td><td>0</td><td><span class=zero-hits>for _, case in test.cases do</span></td></tr>
|
||||
<tr><td>135</td><td>0</td><td><span class=zero-hits>any_focused = any_focused or case.focus</span></td></tr>
|
||||
<tr><td>136</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>137</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>138</td><td>0</td><td><span class=zero-hits>if not any_focused then</span></td></tr>
|
||||
<tr><td>139</td><td>0</td><td><span class=zero-hits>return</span></td></tr>
|
||||
<tr><td>140</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>141</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>142</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>143</td><td>24</td><td><span class=low-hits>print(color.white(test.name))</span></td></tr>
|
||||
<tr><td>144</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>145</td><td>24</td><td><span class=low-hits>for _, case in test.cases do</span></td></tr>
|
||||
<tr><td>146</td><td>73</td><td><span class=low-hits>local status = ({</span></td></tr>
|
||||
<tr><td>147</td><td>73</td><td><span class=low-hits>[PASS] = color.green("PASS"),</span></td></tr>
|
||||
<tr><td>148</td><td>73</td><td><span class=low-hits>[FAIL] = color.red("FAIL"),</span></td></tr>
|
||||
<tr><td>149</td><td>73</td><td><span class=low-hits>[NONE] = color.orange("NONE"),</span></td></tr>
|
||||
<tr><td>150</td><td>73</td><td><span class=low-hits>[ERROR] = color.red("FAIL"),</span></td></tr>
|
||||
<tr><td>151</td><td>73</td><td><span class=low-hits>[SKIPPED] = color.yellow("SKIP"),</span></td></tr>
|
||||
<tr><td>152</td><td>73</td><td><span class=low-hits>})[case.result]</span></td></tr>
|
||||
<tr><td>153</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>154</td><td>73</td><td><span class=low-hits>local line = case.result == FAIL and color.red(`{case.line}:`) or ""</span></td></tr>
|
||||
<tr><td>155</td><td>73</td><td><span class=low-hits>if check_for_focused and case.focus == false and test.focus == false then</span></td></tr>
|
||||
<tr><td>156</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
|
||||
<tr><td>157</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>158</td><td>73</td><td><span class=low-hits>print(`{status}{WALL} {line}{color.gray(case.name)}`)</span></td></tr>
|
||||
<tr><td>159</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>160</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>161</td><td>24</td><td><span class=low-hits>if test.error then</span></td></tr>
|
||||
<tr><td>162</td><td>0</td><td><span class=zero-hits>print(color.gray("error: ") .. color.red(test.error.message))</span></td></tr>
|
||||
<tr><td>163</td><td>0</td><td><span class=zero-hits>print(color.gray("trace: ") .. color.red(test.error.trace))</span></td></tr>
|
||||
<tr><td>164</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>165</td><td>24</td><td><span class=low-hits>print()</span></td></tr>
|
||||
<tr><td>166</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>167</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>168</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>169</td><td>1</td><td><span class=low-hits>local function CASE(name: string)</span></td></tr>
|
||||
<tr><td>170</td><td>73</td><td><span class=low-hits>skip = false</span></td></tr>
|
||||
<tr><td>171</td><td>73</td><td><span class=low-hits>assert(test, "no active test")</span></td></tr>
|
||||
<tr><td>172</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>173</td><td>73</td><td><span class=low-hits>local case = {</span></td></tr>
|
||||
<tr><td>174</td><td>73</td><td><span class=low-hits>name = name,</span></td></tr>
|
||||
<tr><td>175</td><td>73</td><td><span class=low-hits>result = NONE,</span></td></tr>
|
||||
<tr><td>176</td><td>73</td><td><span class=low-hits>focus = false,</span></td></tr>
|
||||
<tr><td>177</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>178</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>179</td><td>73</td><td><span class=low-hits>test.case = case</span></td></tr>
|
||||
<tr><td>180</td><td>73</td><td><span class=low-hits>table.insert(test.cases, case)</span></td></tr>
|
||||
<tr><td>181</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>182</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>183</td><td>1</td><td><span class=low-hits>local function CHECK_EXPECT_ERR(fn, ...)</span></td></tr>
|
||||
<tr><td>184</td><td>9</td><td><span class=low-hits>assert(test, "no active test")</span></td></tr>
|
||||
<tr><td>185</td><td>9</td><td><span class=low-hits>local case = test.case</span></td></tr>
|
||||
<tr><td>186</td><td>9</td><td><span class=low-hits>if not case then</span></td></tr>
|
||||
<tr><td>187</td><td>0</td><td><span class=zero-hits>CASE("")</span></td></tr>
|
||||
<tr><td>188</td><td>0</td><td><span class=zero-hits>case = test.case</span></td></tr>
|
||||
<tr><td>189</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>190</td><td>9</td><td><span class=low-hits>assert(case, "no active case")</span></td></tr>
|
||||
<tr><td>191</td><td>9</td><td><span class=low-hits>if case.result ~= FAIL then</span></td></tr>
|
||||
<tr><td>192</td><td>9</td><td><span class=low-hits>local ok, err = pcall(fn, ...)</span></td></tr>
|
||||
<tr><td>193</td><td>9</td><td><span class=low-hits>case.result = if ok then FAIL else PASS</span></td></tr>
|
||||
<tr><td>194</td><td>9</td><td><span class=low-hits>if skip then</span></td></tr>
|
||||
<tr><td>195</td><td>0</td><td><span class=zero-hits>case.result = SKIPPED</span></td></tr>
|
||||
<tr><td>196</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>197</td><td>9</td><td><span class=low-hits>case.line = debug.info(stack and stack + 1 or 2, "l")</span></td></tr>
|
||||
<tr><td>198</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>199</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>200</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>201</td><td>1</td><td><span class=low-hits>local function CHECK<T>(value: T, stack: number?): T?</span></td></tr>
|
||||
<tr><td>202</td><td>1195</td><td><span class=high-hits>assert(test, "no active test")</span></td></tr>
|
||||
<tr><td>203</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>204</td><td>1195</td><td><span class=high-hits>local case = test.case</span></td></tr>
|
||||
<tr><td>205</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>206</td><td>1195</td><td><span class=high-hits>if not case then</span></td></tr>
|
||||
<tr><td>207</td><td>9</td><td><span class=low-hits>CASE("")</span></td></tr>
|
||||
<tr><td>208</td><td>9</td><td><span class=low-hits>case = test.case</span></td></tr>
|
||||
<tr><td>209</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>210</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>211</td><td>1195</td><td><span class=high-hits>assert(case, "no active case")</span></td></tr>
|
||||
<tr><td>212</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>213</td><td>1195</td><td><span class=high-hits>if case.result ~= FAIL then</span></td></tr>
|
||||
<tr><td>214</td><td>1195</td><td><span class=high-hits>case.result = value and PASS or FAIL</span></td></tr>
|
||||
<tr><td>215</td><td>1195</td><td><span class=high-hits>if skip then</span></td></tr>
|
||||
<tr><td>216</td><td>1</td><td><span class=low-hits>case.result = SKIPPED</span></td></tr>
|
||||
<tr><td>217</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>218</td><td>1195</td><td><span class=high-hits>case.line = debug.info(stack and stack + 1 or 2, "l")</span></td></tr>
|
||||
<tr><td>219</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>220</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>221</td><td>1195</td><td><span class=high-hits>return value</span></td></tr>
|
||||
<tr><td>222</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>223</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>224</td><td>1</td><td><span class=low-hits>local function TEST(name: string, fn: () -> ())</span></td></tr>
|
||||
<tr><td>225</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>226</td><td>24</td><td><span class=low-hits>test = {</span></td></tr>
|
||||
<tr><td>227</td><td>24</td><td><span class=low-hits>name = name,</span></td></tr>
|
||||
<tr><td>228</td><td>24</td><td><span class=low-hits>cases = {},</span></td></tr>
|
||||
<tr><td>229</td><td>24</td><td><span class=low-hits>duration = 0,</span></td></tr>
|
||||
<tr><td>230</td><td>24</td><td><span class=low-hits>focus = false,</span></td></tr>
|
||||
<tr><td>231</td><td>24</td><td><span class=low-hits>fn = fn</span></td></tr>
|
||||
<tr><td>232</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>233</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>234</td><td>24</td><td><span class=low-hits>table.insert(tests, test)</span></td></tr>
|
||||
<tr><td>235</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>236</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>237</td><td>1</td><td><span class=low-hits>local function FOCUS()</span></td></tr>
|
||||
<tr><td>238</td><td>0</td><td><span class=zero-hits>assert(test, "no active test")</span></td></tr>
|
||||
<tr><td>239</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>240</td><td>0</td><td><span class=zero-hits>check_for_focused = true</span></td></tr>
|
||||
<tr><td>241</td><td>0</td><td><span class=zero-hits>if test.case then</span></td></tr>
|
||||
<tr><td>242</td><td>0</td><td><span class=zero-hits>test.case.focus = true</span></td></tr>
|
||||
<tr><td>243</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>244</td><td>0</td><td><span class=zero-hits>test.focus = true</span></td></tr>
|
||||
<tr><td>245</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>246</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>247</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>248</td><td>1</td><td><span class=low-hits>local function FINISH(): boolean</span></td></tr>
|
||||
<tr><td>249</td><td>1</td><td><span class=low-hits>local success = true</span></td></tr>
|
||||
<tr><td>250</td><td>1</td><td><span class=low-hits>local total_cases = 0</span></td></tr>
|
||||
<tr><td>251</td><td>1</td><td><span class=low-hits>local passed_cases = 0</span></td></tr>
|
||||
<tr><td>252</td><td>1</td><td><span class=low-hits>local passed_focus_cases = 0</span></td></tr>
|
||||
<tr><td>253</td><td>1</td><td><span class=low-hits>local total_focus_cases = 0</span></td></tr>
|
||||
<tr><td>254</td><td>1</td><td><span class=low-hits>local duration = 0</span></td></tr>
|
||||
<tr><td>255</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>256</td><td>1</td><td><span class=low-hits>for _, t in tests do</span></td></tr>
|
||||
<tr><td>257</td><td>24</td><td><span class=low-hits>if check_for_focused and not t.focus then</span></td></tr>
|
||||
<tr><td>258</td><td>0</td><td><span class=zero-hits>continue</span></td></tr>
|
||||
<tr><td>259</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>260</td><td>24</td><td><span class=low-hits>test = t</span></td></tr>
|
||||
<tr><td>261</td><td>24</td><td><span class=low-hits>fn = t.fn</span></td></tr>
|
||||
<tr><td>262</td><td>24</td><td><span class=low-hits>local start = os.clock()</span></td></tr>
|
||||
<tr><td>263</td><td>24</td><td><span class=low-hits>local err</span></td></tr>
|
||||
<tr><td>264</td><td>24</td><td><span class=low-hits>local success = xpcall(fn, function(m: string)</span></td></tr>
|
||||
<tr><td>265</td><td>0</td><td><span class=zero-hits>err = { message = m, trace = debug.traceback(nil, 2) }</span></td></tr>
|
||||
<tr><td>266</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
|
||||
<tr><td>267</td><td>24</td><td><span class=low-hits>test.duration = os.clock() - start</span></td></tr>
|
||||
<tr><td>268</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>269</td><td>24</td><td><span class=low-hits>if not test.case then</span></td></tr>
|
||||
<tr><td>270</td><td>0</td><td><span class=zero-hits>CASE("")</span></td></tr>
|
||||
<tr><td>271</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>272</td><td>24</td><td><span class=low-hits>assert(test.case, "no active case")</span></td></tr>
|
||||
<tr><td>273</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>274</td><td>24</td><td><span class=low-hits>if not success then</span></td></tr>
|
||||
<tr><td>275</td><td>0</td><td><span class=zero-hits>test.case.result = ERROR</span></td></tr>
|
||||
<tr><td>276</td><td>0</td><td><span class=zero-hits>test.error = err</span></td></tr>
|
||||
<tr><td>277</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>278</td><td>24</td><td><span class=low-hits>collectgarbage()</span></td></tr>
|
||||
<tr><td>279</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>280</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>281</td><td>1</td><td><span class=low-hits>for _, test in tests do</span></td></tr>
|
||||
<tr><td>282</td><td>24</td><td><span class=low-hits>duration += test.duration</span></td></tr>
|
||||
<tr><td>283</td><td>24</td><td><span class=low-hits>for _, case in test.cases do</span></td></tr>
|
||||
<tr><td>284</td><td>73</td><td><span class=low-hits>total_cases += 1</span></td></tr>
|
||||
<tr><td>285</td><td>73</td><td><span class=low-hits>if case.focus or test.focus then</span></td></tr>
|
||||
<tr><td>286</td><td>0</td><td><span class=zero-hits>total_focus_cases += 1</span></td></tr>
|
||||
<tr><td>287</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>288</td><td>73</td><td><span class=low-hits>if case.result == PASS or case.result == NONE or case.result == SKIPPED then</span></td></tr>
|
||||
<tr><td>289</td><td>73</td><td><span class=low-hits>if case.focus or test.focus then</span></td></tr>
|
||||
<tr><td>290</td><td>0</td><td><span class=zero-hits>passed_focus_cases += 1</span></td></tr>
|
||||
<tr><td>291</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>292</td><td>73</td><td><span class=low-hits>passed_cases += 1</span></td></tr>
|
||||
<tr><td>293</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>294</td><td>0</td><td><span class=zero-hits>success = false</span></td></tr>
|
||||
<tr><td>295</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>296</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>297</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>298</td><td>24</td><td><span class=low-hits>output_test_result(test)</span></td></tr>
|
||||
<tr><td>299</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>300</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>301</td><td>1</td><td><span class=low-hits>print(color.gray(string.format(`{passed_cases}/{total_cases} test cases passed in %.3f ms.`, duration * 1e3)))</span></td></tr>
|
||||
<tr><td>302</td><td>1</td><td><span class=low-hits>if check_for_focused then</span></td></tr>
|
||||
<tr><td>303</td><td>0</td><td><span class=zero-hits>print(color.gray(`{passed_focus_cases}/{total_focus_cases} focused test cases passed`))</span></td></tr>
|
||||
<tr><td>304</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>305</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>306</td><td>1</td><td><span class=low-hits>local fails = total_cases - passed_cases</span></td></tr>
|
||||
<tr><td>307</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>308</td><td>1</td><td><span class=low-hits>print((fails > 0 and color.red or color.green)(`{fails} {fails == 1 and "fail" or "fails"}`))</span></td></tr>
|
||||
<tr><td>309</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>310</td><td>1</td><td><span class=low-hits>check_for_focused = false</span></td></tr>
|
||||
<tr><td>311</td><td>1</td><td><span class=low-hits>return success, table.clear(tests)</span></td></tr>
|
||||
<tr><td>312</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>313</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>314</td><td>1</td><td><span class=low-hits>local function SKIP()</span></td></tr>
|
||||
<tr><td>315</td><td>1</td><td><span class=low-hits>skip = true</span></td></tr>
|
||||
<tr><td>316</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>317</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>318</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>319</td><td><span class='text-muted'>N/A</span></td><td>-- Benchmarking</td>></tr>
|
||||
<tr><td>320</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>321</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>322</td><td>0</td><td><span class=zero-hits>type Bench = {</span></td></tr>
|
||||
<tr><td>323</td><td>0</td><td><span class=zero-hits>time_start: number?,</span></td></tr>
|
||||
<tr><td>324</td><td>0</td><td><span class=zero-hits>memory_start: number?,</span></td></tr>
|
||||
<tr><td>325</td><td>0</td><td><span class=zero-hits>iterations: number?,</span></td></tr>
|
||||
<tr><td>326</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>327</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>328</td><td>1</td><td><span class=low-hits>local bench: Bench?</span></td></tr>
|
||||
<tr><td>329</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>330</td><td>1</td><td><span class=low-hits>function START(iter: number?): number</span></td></tr>
|
||||
<tr><td>331</td><td>1</td><td><span class=low-hits>local n = iter or 1</span></td></tr>
|
||||
<tr><td>332</td><td>1</td><td><span class=low-hits>assert(n > 0, "iterations must be greater than 0")</span></td></tr>
|
||||
<tr><td>333</td><td>1</td><td><span class=low-hits>assert(bench, "no active benchmark")</span></td></tr>
|
||||
<tr><td>334</td><td>1</td><td><span class=low-hits>assert(not bench.time_start, "clock was already started")</span></td></tr>
|
||||
<tr><td>335</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>336</td><td>1</td><td><span class=low-hits>bench.iterations = n</span></td></tr>
|
||||
<tr><td>337</td><td>1</td><td><span class=low-hits>bench.memory_start = gcinfo()</span></td></tr>
|
||||
<tr><td>338</td><td>1</td><td><span class=low-hits>bench.time_start = os.clock()</span></td></tr>
|
||||
<tr><td>339</td><td>1</td><td><span class=low-hits>return n</span></td></tr>
|
||||
<tr><td>340</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>341</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>342</td><td>1</td><td><span class=low-hits>local function BENCH(name: string, fn: () -> ())</span></td></tr>
|
||||
<tr><td>343</td><td>3</td><td><span class=low-hits>local active = bench</span></td></tr>
|
||||
<tr><td>344</td><td>3</td><td><span class=low-hits>assert(not active, "a benchmark is already in progress")</span></td></tr>
|
||||
<tr><td>345</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>346</td><td>3</td><td><span class=low-hits>bench = {}</span></td></tr>
|
||||
<tr><td>347</td><td>3</td><td><span class=low-hits>assert(bench);</span></td></tr>
|
||||
<tr><td>348</td><td>3</td><td><span class=low-hits>(collectgarbage :: any)("collect")</span></td></tr>
|
||||
<tr><td>349</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>350</td><td>3</td><td><span class=low-hits>local mem_start = gcinfo()</span></td></tr>
|
||||
<tr><td>351</td><td>3</td><td><span class=low-hits>local time_start = os.clock()</span></td></tr>
|
||||
<tr><td>352</td><td>3</td><td><span class=low-hits>local err_msg: string?</span></td></tr>
|
||||
<tr><td>353</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>354</td><td>3</td><td><span class=low-hits>local success = xpcall(fn, function(m: string)</span></td></tr>
|
||||
<tr><td>355</td><td>0</td><td><span class=zero-hits>err_msg = m .. debug.traceback(nil, 2)</span></td></tr>
|
||||
<tr><td>356</td><td><span class='text-muted'>N/A</span></td><td>end)</td>></tr>
|
||||
<tr><td>357</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>358</td><td>3</td><td><span class=low-hits>local time_stop = os.clock()</span></td></tr>
|
||||
<tr><td>359</td><td>3</td><td><span class=low-hits>local mem_stop = gcinfo()</span></td></tr>
|
||||
<tr><td>360</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>361</td><td>3</td><td><span class=low-hits>if not success then</span></td></tr>
|
||||
<tr><td>362</td><td>0</td><td><span class=zero-hits>print(`{WALL}{color.red("ERROR")}{WALL} {name}`)</span></td></tr>
|
||||
<tr><td>363</td><td>0</td><td><span class=zero-hits>print(color.gray(err_msg :: string))</span></td></tr>
|
||||
<tr><td>364</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>365</td><td>3</td><td><span class=low-hits>time_start = bench.time_start or time_start</span></td></tr>
|
||||
<tr><td>366</td><td>3</td><td><span class=low-hits>mem_start = bench.memory_start or mem_start</span></td></tr>
|
||||
<tr><td>367</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>368</td><td>3</td><td><span class=low-hits>local n = bench.iterations or 1</span></td></tr>
|
||||
<tr><td>369</td><td>3</td><td><span class=low-hits>local d, d_unit = convert_units("s", (time_stop - time_start) / n)</span></td></tr>
|
||||
<tr><td>370</td><td>3</td><td><span class=low-hits>local a, a_unit = convert_units("B", math.round((mem_stop - mem_start) / n * 1e3))</span></td></tr>
|
||||
<tr><td>371</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>372</td><td>3</td><td><span class=low-hits>local function round(x: number): string</span></td></tr>
|
||||
<tr><td>373</td><td>6</td><td><span class=low-hits>return x > 0 and x < 10 and (x - math.floor(x)) > 0 and string.format("%2.1f", x)</span></td></tr>
|
||||
<tr><td>374</td><td>6</td><td><span class=low-hits>or string.format("%3.f", x)</span></td></tr>
|
||||
<tr><td>375</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>376</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>377</td><td>3</td><td><span class=low-hits>print(</span></td></tr>
|
||||
<tr><td>378</td><td>3</td><td><span class=low-hits>string.format(</span></td></tr>
|
||||
<tr><td>379</td><td>3</td><td><span class=low-hits>`%s %s %s %s{WALL} %s`,</span></td></tr>
|
||||
<tr><td>380</td><td>3</td><td><span class=low-hits>color.gray(round(d)),</span></td></tr>
|
||||
<tr><td>381</td><td>3</td><td><span class=low-hits>d_unit,</span></td></tr>
|
||||
<tr><td>382</td><td>3</td><td><span class=low-hits>color.gray(round(a)),</span></td></tr>
|
||||
<tr><td>383</td><td>3</td><td><span class=low-hits>a_unit,</span></td></tr>
|
||||
<tr><td>384</td><td>3</td><td><span class=low-hits>color.gray(name)</span></td></tr>
|
||||
<tr><td>385</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
|
||||
<tr><td>386</td><td>0</td><td><span class=zero-hits>)</span></td></tr>
|
||||
<tr><td>387</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>388</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>389</td><td>3</td><td><span class=low-hits>bench = nil</span></td></tr>
|
||||
<tr><td>390</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>391</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>392</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>393</td><td><span class='text-muted'>N/A</span></td><td>-- Printing</td>></tr>
|
||||
<tr><td>394</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>395</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>396</td><td>1</td><td><span class=low-hits>local function print2(v: unknown)</span></td></tr>
|
||||
<tr><td>397</td><td>0</td><td><span class=zero-hits>type Buffer = { n: number, [number]: string }</span></td></tr>
|
||||
<tr><td>398</td><td>0</td><td><span class=zero-hits>type Cyclic = { n: number, [{}]: number }</span></td></tr>
|
||||
<tr><td>399</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>400</td><td><span class='text-muted'>N/A</span></td><td>-- overkill concatenationless string buffer</td>></tr>
|
||||
<tr><td>401</td><td>0</td><td><span class=zero-hits>local function tos(value: any, stack: number, str: Buffer, cyclic: Cyclic)</span></td></tr>
|
||||
<tr><td>402</td><td>0</td><td><span class=zero-hits>local TAB = " "</span></td></tr>
|
||||
<tr><td>403</td><td>0</td><td><span class=zero-hits>local indent = table.concat(table.create(stack, TAB))</span></td></tr>
|
||||
<tr><td>404</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>405</td><td>0</td><td><span class=zero-hits>if type(value) == "string" then</span></td></tr>
|
||||
<tr><td>406</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
|
||||
<tr><td>407</td><td>0</td><td><span class=zero-hits>str[n + 1] = "\""</span></td></tr>
|
||||
<tr><td>408</td><td>0</td><td><span class=zero-hits>str[n + 2] = value</span></td></tr>
|
||||
<tr><td>409</td><td>0</td><td><span class=zero-hits>str[n + 3] = "\""</span></td></tr>
|
||||
<tr><td>410</td><td>0</td><td><span class=zero-hits>str.n = n + 3</span></td></tr>
|
||||
<tr><td>411</td><td>0</td><td><span class=zero-hits>elseif type(value) ~= "table" then</span></td></tr>
|
||||
<tr><td>412</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
|
||||
<tr><td>413</td><td>0</td><td><span class=zero-hits>str[n + 1] = value == nil and "nil" or tostring(value)</span></td></tr>
|
||||
<tr><td>414</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
|
||||
<tr><td>415</td><td>0</td><td><span class=zero-hits>elseif next(value) == nil then</span></td></tr>
|
||||
<tr><td>416</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
|
||||
<tr><td>417</td><td>0</td><td><span class=zero-hits>str[n + 1] = "{}"</span></td></tr>
|
||||
<tr><td>418</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
|
||||
<tr><td>419</td><td>0</td><td><span class=zero-hits>else -- is table</span></td></tr>
|
||||
<tr><td>420</td><td>0</td><td><span class=zero-hits>local tabbed_indent = indent .. TAB</span></td></tr>
|
||||
<tr><td>421</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>422</td><td>0</td><td><span class=zero-hits>if cyclic[value] then</span></td></tr>
|
||||
<tr><td>423</td><td>0</td><td><span class=zero-hits>str.n += 1</span></td></tr>
|
||||
<tr><td>424</td><td>0</td><td><span class=zero-hits>str[str.n] = color.gray(`CYCLIC REF {cyclic[value]}`)</span></td></tr>
|
||||
<tr><td>425</td><td>0</td><td><span class=zero-hits>return</span></td></tr>
|
||||
<tr><td>426</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>427</td><td>0</td><td><span class=zero-hits>cyclic.n += 1</span></td></tr>
|
||||
<tr><td>428</td><td>0</td><td><span class=zero-hits>cyclic[value] = cyclic.n</span></td></tr>
|
||||
<tr><td>429</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>430</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>431</td><td>0</td><td><span class=zero-hits>str.n += 3</span></td></tr>
|
||||
<tr><td>432</td><td>0</td><td><span class=zero-hits>str[str.n - 2] = "{ "</span></td></tr>
|
||||
<tr><td>433</td><td>0</td><td><span class=zero-hits>str[str.n - 1] = color.gray(tostring(cyclic[value]))</span></td></tr>
|
||||
<tr><td>434</td><td>0</td><td><span class=zero-hits>str[str.n - 0] = "\n"</span></td></tr>
|
||||
<tr><td>435</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>436</td><td>0</td><td><span class=zero-hits>local i, v = next(value, nil)</span></td></tr>
|
||||
<tr><td>437</td><td>0</td><td><span class=zero-hits>while v ~= nil do</span></td></tr>
|
||||
<tr><td>438</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
|
||||
<tr><td>439</td><td>0</td><td><span class=zero-hits>str[n + 1] = tabbed_indent</span></td></tr>
|
||||
<tr><td>440</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>441</td><td>0</td><td><span class=zero-hits>if type(i) ~= "string" then</span></td></tr>
|
||||
<tr><td>442</td><td>0</td><td><span class=zero-hits>str[n + 2] = "["</span></td></tr>
|
||||
<tr><td>443</td><td>0</td><td><span class=zero-hits>str[n + 3] = tostring(i)</span></td></tr>
|
||||
<tr><td>444</td><td>0</td><td><span class=zero-hits>str[n + 4] = "]"</span></td></tr>
|
||||
<tr><td>445</td><td>0</td><td><span class=zero-hits>n += 4</span></td></tr>
|
||||
<tr><td>446</td><td>0</td><td><span class=zero-hits>else</span></td></tr>
|
||||
<tr><td>447</td><td>0</td><td><span class=zero-hits>str[n + 2] = tostring(i)</span></td></tr>
|
||||
<tr><td>448</td><td>0</td><td><span class=zero-hits>n += 2</span></td></tr>
|
||||
<tr><td>449</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>450</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>451</td><td>0</td><td><span class=zero-hits>str[n + 1] = " = "</span></td></tr>
|
||||
<tr><td>452</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
|
||||
<tr><td>453</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>454</td><td>0</td><td><span class=zero-hits>tos(v, stack + 1, str, cyclic)</span></td></tr>
|
||||
<tr><td>455</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>456</td><td>0</td><td><span class=zero-hits>i, v = next(value, i)</span></td></tr>
|
||||
<tr><td>457</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>458</td><td>0</td><td><span class=zero-hits>n = str.n</span></td></tr>
|
||||
<tr><td>459</td><td>0</td><td><span class=zero-hits>str[n + 1] = v ~= nil and ",\n" or "\n"</span></td></tr>
|
||||
<tr><td>460</td><td>0</td><td><span class=zero-hits>str.n = n + 1</span></td></tr>
|
||||
<tr><td>461</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>462</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>463</td><td>0</td><td><span class=zero-hits>local n = str.n</span></td></tr>
|
||||
<tr><td>464</td><td>0</td><td><span class=zero-hits>str[n + 1] = indent</span></td></tr>
|
||||
<tr><td>465</td><td>0</td><td><span class=zero-hits>str[n + 2] = "}"</span></td></tr>
|
||||
<tr><td>466</td><td>0</td><td><span class=zero-hits>str.n = n + 2</span></td></tr>
|
||||
<tr><td>467</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>468</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>469</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>470</td><td>0</td><td><span class=zero-hits>local str = { n = 0 }</span></td></tr>
|
||||
<tr><td>471</td><td>0</td><td><span class=zero-hits>local cyclic = { n = 0 }</span></td></tr>
|
||||
<tr><td>472</td><td>0</td><td><span class=zero-hits>tos(v, 0, str, cyclic)</span></td></tr>
|
||||
<tr><td>473</td><td>0</td><td><span class=zero-hits>print(table.concat(str))</span></td></tr>
|
||||
<tr><td>474</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>475</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>476</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>477</td><td><span class='text-muted'>N/A</span></td><td>-- Equality</td>></tr>
|
||||
<tr><td>478</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>479</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>480</td><td>1</td><td><span class=low-hits>local function shallow_eq(a: {}, b: {}): boolean</span></td></tr>
|
||||
<tr><td>481</td><td>0</td><td><span class=zero-hits>if #a ~= #b then</span></td></tr>
|
||||
<tr><td>482</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>483</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>484</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>485</td><td>0</td><td><span class=zero-hits>for i, v in next, a do</span></td></tr>
|
||||
<tr><td>486</td><td>0</td><td><span class=zero-hits>if b[i] ~= v then</span></td></tr>
|
||||
<tr><td>487</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>488</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>489</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>490</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>491</td><td>0</td><td><span class=zero-hits>for i, v in next, b do</span></td></tr>
|
||||
<tr><td>492</td><td>0</td><td><span class=zero-hits>if a[i] ~= v then</span></td></tr>
|
||||
<tr><td>493</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>494</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>495</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>496</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>497</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
|
||||
<tr><td>498</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>499</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>500</td><td>1</td><td><span class=low-hits>local function deep_eq(a: {}, b: {}): boolean</span></td></tr>
|
||||
<tr><td>501</td><td>0</td><td><span class=zero-hits>if #a ~= #b then</span></td></tr>
|
||||
<tr><td>502</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>503</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>504</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>505</td><td>0</td><td><span class=zero-hits>for i, v in next, a do</span></td></tr>
|
||||
<tr><td>506</td><td>0</td><td><span class=zero-hits>if type(b[i]) == "table" and type(v) == "table" then</span></td></tr>
|
||||
<tr><td>507</td><td>0</td><td><span class=zero-hits>if deep_eq(b[i], v) == false then</span></td></tr>
|
||||
<tr><td>508</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>509</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>510</td><td>0</td><td><span class=zero-hits>elseif b[i] ~= v then</span></td></tr>
|
||||
<tr><td>511</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>512</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>513</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>514</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>515</td><td>0</td><td><span class=zero-hits>for i, v in next, b do</span></td></tr>
|
||||
<tr><td>516</td><td>0</td><td><span class=zero-hits>if type(a[i]) == "table" and type(v) == "table" then</span></td></tr>
|
||||
<tr><td>517</td><td>0</td><td><span class=zero-hits>if deep_eq(a[i], v) == false then</span></td></tr>
|
||||
<tr><td>518</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>519</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>520</td><td>0</td><td><span class=zero-hits>elseif a[i] ~= v then</span></td></tr>
|
||||
<tr><td>521</td><td>0</td><td><span class=zero-hits>return false</span></td></tr>
|
||||
<tr><td>522</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>523</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>524</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>525</td><td>0</td><td><span class=zero-hits>return true</span></td></tr>
|
||||
<tr><td>526</td><td><span class='text-muted'>N/A</span></td><td>end</td>></tr>
|
||||
<tr><td>527</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>528</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>529</td><td><span class='text-muted'>N/A</span></td><td>-- Return</td>></tr>
|
||||
<tr><td>530</td><td><span class='text-muted'>N/A</span></td><td>--------------------------------------------------------------------------------</td>></tr>
|
||||
<tr><td>531</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>532</td><td>1</td><td><span class=low-hits>return {</span></td></tr>
|
||||
<tr><td>533</td><td>1</td><td><span class=low-hits>test = function()</span></td></tr>
|
||||
<tr><td>534</td><td>1</td><td><span class=low-hits>return {</span></td></tr>
|
||||
<tr><td>535</td><td>1</td><td><span class=low-hits>TEST = TEST,</span></td></tr>
|
||||
<tr><td>536</td><td>1</td><td><span class=low-hits>CASE = CASE,</span></td></tr>
|
||||
<tr><td>537</td><td>1</td><td><span class=low-hits>CHECK = CHECK,</span></td></tr>
|
||||
<tr><td>538</td><td>1</td><td><span class=low-hits>FINISH = FINISH,</span></td></tr>
|
||||
<tr><td>539</td><td>1</td><td><span class=low-hits>SKIP = SKIP,</span></td></tr>
|
||||
<tr><td>540</td><td>1</td><td><span class=low-hits>FOCUS = FOCUS,</span></td></tr>
|
||||
<tr><td>541</td><td>1</td><td><span class=low-hits>CHECK_EXPECT_ERR = CHECK_EXPECT_ERR,</span></td></tr>
|
||||
<tr><td>542</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
<tr><td>543</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>544</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>545</td><td>1</td><td><span class=low-hits>benchmark = function()</span></td></tr>
|
||||
<tr><td>546</td><td>1</td><td><span class=low-hits>return BENCH, START</span></td></tr>
|
||||
<tr><td>547</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>548</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>549</td><td>1</td><td><span class=low-hits>disable_formatting = function()</span></td></tr>
|
||||
<tr><td>550</td><td>0</td><td><span class=zero-hits>disable_ansi = true</span></td></tr>
|
||||
<tr><td>551</td><td><span class='text-muted'>N/A</span></td><td>end,</td>></tr>
|
||||
<tr><td>552</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>553</td><td>1</td><td><span class=low-hits>print = print2,</span></td></tr>
|
||||
<tr><td>554</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>555</td><td>1</td><td><span class=low-hits>seq = shallow_eq,</span></td></tr>
|
||||
<tr><td>556</td><td>1</td><td><span class=low-hits>deq = deep_eq,</span></td></tr>
|
||||
<tr><td>557</td><td><span class='text-muted'>N/A</span></td><td></td>></tr>
|
||||
<tr><td>558</td><td>1</td><td><span class=low-hits>color = color,</span></td></tr>
|
||||
<tr><td>559</td><td>0</td><td><span class=zero-hits>}</span></td></tr>
|
||||
</tbody></table></body></html>
|
||||
2044
docs/public/coverage/tests.luau.html
vendored
2044
docs/public/coverage/tests.luau.html
vendored
File diff suppressed because it is too large
Load diff
|
|
@ -1,41 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="1080" height="1080" viewBox="0 0 1080 1080" xml:space="preserve">
|
||||
<desc>Created with Fabric.js 5.2.4</desc>
|
||||
<defs>
|
||||
</defs>
|
||||
<rect x="0" y="0" width="100%" height="100%" fill="transparent"></rect>
|
||||
<g transform="matrix(1 0 0 1 540 540)" id="09ac800d-29f3-4193-b9f5-faf19e8b1726" >
|
||||
<rect style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(255,255,255); fill-rule: nonzero; opacity: 1; visibility: hidden;" vector-effect="non-scaling-stroke" x="-540" y="-540" rx="0" ry="0" width="1080" height="1080" />
|
||||
</g>
|
||||
<g transform="matrix(Infinity NaN NaN Infinity 0 0)" id="619f0364-53a0-4caa-97e3-8f543e0cc17f" >
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(17.7 0 0 17.7 540 540)" >
|
||||
<g style="" vector-effect="non-scaling-stroke" >
|
||||
<g transform="matrix(1 0 0 1 -18.25 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: nonzero; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-5, -9)" d="M 5 14 C 5.8 14 6 13.3333 6 13 L 6 4 L 0 4 L 0 0 L 6 0 L 10 0 L 10 13 C 10 17 6.66667 18 5 18 L 0 18 L 0 14 L 5 14 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 16.75 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: nonzero; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-40, -9)" d="M 46.5 4 L 46.5 0 L 39 0 C 37.1667 0 33.5 1.1 33.5 5.5 C 33.5 9.9 36.8333 11 38.5 11 L 41 11 C 41.5 11 42.5 11.3 42.5 12.5 C 42.5 13.7 41.5 14 41 14 L 33.5 14 L 33.5 18 L 41.5 18 C 43.1667 18 46.5 16.9 46.5 12.5 C 46.5 8.1 43.1667 7 41.5 7 L 39 7 C 38.5 7 37.5 6.7 37.5 5.5 C 37.5 4.3 38.5 4 39 4 L 46.5 4 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 3.25 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: evenodd; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-26.5, -9)" d="M 32.5 0 L 32.5 4 L 30.5 4 C 28.5 4 24.5 5 24.5 9 C 24.5 11.0835 25.5853 12.3531 26.9078 13.0914 L 22.4606 14.661 C 21.2893 13.3156 20.5 11.4775 20.5 9 C 20.5 1.8 27.1667 0 30.5 0 L 32.5 0 Z M 24.4656 16.3357 C 26.5037 17.5803 28.8905 18 30.5 18 L 32.5 18 L 32.5 14 L 31.0833 14 L 24.4656 16.3357 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
<g transform="matrix(1 0 0 1 -5 0)" >
|
||||
<path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(52,81,178); fill-rule: evenodd; opacity: 1;" vector-effect="non-scaling-stroke" transform=" translate(-18.25, -9)" d="M 25.3793 0 C 24.766 0.241156 24.1568 0.53354 23.571 0.885014 C 22.1712 1.72492 20.9038 2.91123 20.0606 4.5 L 11 4.5 L 11 0 L 25.3793 0 Z M 25.5 4.39421 C 25.445 4.42876 25.3906 4.46402 25.3368 4.5 L 25.5 4.5 L 25.5 4.39421 Z M 20.0606 13.5 C 20.9038 15.0888 22.1712 16.2751 23.571 17.115 C 24.1568 17.4665 24.766 17.7588 25.3793 18 L 11 18 L 11 13.5 L 20.0606 13.5 Z M 19.1854 7 C 19.0649 7.62348 19 8.28956 19 9 C 19 9.71044 19.0649 10.3765 19.1854 11 L 11 11 L 11 7 L 19.1854 7 Z" stroke-linecap="round" />
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
<g transform="matrix(NaN NaN NaN NaN 0 0)" >
|
||||
<g style="" >
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 3.9 KiB |
|
|
@ -1,81 +0,0 @@
|
|||
## Learning
|
||||
|
||||
- [Jecs Demo](https://github.com/Ukendio/jecs/tree/main/demo)
|
||||
- [Jecs Examples](https://github.com/Ukendio/jecs/tree/main/examples)
|
||||
- [An Introduction to ECS for Robloxians - @Ukendio](https://devforum.roblox.com/t/all-about-entity-component-system/1664447)
|
||||
- [Entities, Components and Systems - Mark Jordan](https://medium.com/ingeniouslysimple/entities-components-and-systems-89c31464240d)
|
||||
- [Why Vanilla ECS is not enough - Sander Mertens](https://ajmmertens.medium.com/why-vanilla-ecs-is-not-enough-d7ed4e3bebe5)
|
||||
- [Formalisation of Concepts behind ECS and Entitas - Maxim Zaks](https://medium.com/@icex33/formalisation-of-concepts-behind-ecs-and-entitas-8efe535d9516)
|
||||
- [Entity Component System and Rendering - Our Machinery](https://ourmachinery.com/post/ecs-and-rendering/)
|
||||
- [Specs and Legion, two very different approaches to ECS - Cora Sherrat](https://csherratt.github.io/blog/posts/specs-and-legion/)
|
||||
- [Where are my Entities and Components - Sander Mertens](https://ajmmertens.medium.com/building-an-ecs-1-where-are-my-entities-and-components-63d07c7da742)
|
||||
- [Archetypes and Vectorization - Sander Mertens](https://medium.com/@ajmmertens/building-an-ecs-2-archetypes-and-vectorization-fe21690805f9)
|
||||
- [Building Games with Entity Relationships - Sander Mertens](https://ajmmertens.medium.com/building-games-in-ecs-with-entity-relationships-657275ba2c6c)
|
||||
- [Why it is time to start thinking of games as databases - Sander Mertens](https://ajmmertens.medium.com/why-it-is-time-to-start-thinking-of-games-as-databases-e7971da33ac3)
|
||||
- [A Roadmap to Entity Relationships - Sander Mertens](https://ajmmertens.medium.com/a-roadmap-to-entity-relationships-5b1d11ebb4eb)
|
||||
- [Making the most of Entity Identifiers - Sander Mertens](https://ajmmertens.medium.com/doing-a-lot-with-a-little-ecs-identifiers-25a72bd2647)
|
||||
- [Why Storing State Machines in ECS is a Bad Idea - Sander Mertens](https://ajmmertens.medium.com/why-storing-state-machines-in-ecs-is-a-bad-idea-742de7a18e59)
|
||||
- [ECS back & forth - Michele Caini](https://skypjack.github.io/2019-02-14-ecs-baf-part-1/)
|
||||
- [Sparse Set - Geeks for Geeks](https://www.geeksforgeeks.org/sparse-set/)
|
||||
- [Taking the Entity-Component-System Architecture Seriously - @alice-i-cecile](https://www.youtube.com/watch?v=VpiprNBEZsk)
|
||||
- [Overwatch Gameplay Architecture and Netcode - Blizzard, GDC](https://www.youtube.com/watch?v=W3aieHjyNvw)
|
||||
- [Data-Oriented Design and C++ - Mike Acton, CppCon](https://www.youtube.com/watch?v=rX0ItVEVjHc)
|
||||
- [Using Rust for Game Development - Catherine West, RustConf](https://www.youtube.com/watch?v=aKLntZcp27M)
|
||||
- [CPU caches and why you should care - Scott Meyers, NDC](https://vimeo.com/97337258)
|
||||
- [Building a fast ECS on top of a slow ECS - @UnitOfTime](https://youtu.be/71RSWVyOMEY)
|
||||
- [Culling the Battlefield: Data Oriented Design in Practice - DICE, GDC](https://www.gdcvault.com/play/1014491/Culling-the-Battlefield-Data-Oriented)
|
||||
- [Game Engine Entity/Object Systems - Bobby Anguelov](https://www.youtube.com/watch?v=jjEsB611kxs)
|
||||
- [Understanding Data Oriented Design for Entity Component Systems - Unity GDC](https://www.youtube.com/watch?v=0_Byw9UMn9g)
|
||||
- [Understanding Data Oriented Design - Unity](https://learn.unity.com/tutorial/part-1-understand-data-oriented-design?courseId=60132919edbc2a56f9d439c3&signup=true&uv=2020.1)
|
||||
- [Data Oriented Design - Richard Fabian](https://www.dataorienteddesign.com/dodbook/dodmain.html)
|
||||
- [Interactive app for browsing systems of City Skylines 2 - @Captain-Of-Coit](https://captain-of-coit.github.io/cs2-ecs-explorer/)
|
||||
- [Awesome Entity Component System (link collection related to ECS) - Jeongseok Lee](https://github.com/jslee02/awesome-entity-component-system)
|
||||
- [Hibitset - DOCS.RS](https://docs.rs/hibitset/0.6.3/hibitset/)
|
||||
|
||||
## 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](/learn/contributing/pull-requests#addons)!
|
||||
|
||||
### Development tools
|
||||
|
||||
#### [jabby](https://github.com/alicesaidhi/jabby)
|
||||
A jecs debugger with a string-based query language and entity editing capabilities.
|
||||
|
||||
#### [jecs_entity_visualiser](https://github.com/Ukendio/jecs/blob/main/tools/entity_visualiser.luau)
|
||||
A simple entity and component visualiser in the output
|
||||
|
||||
#### [jecs_lifetime_tracker](https://github.com/Ukendio/jecs/blob/main/tools/lifetime_tracker.luau)
|
||||
A tool for inspecting entity lifetimes
|
||||
|
||||
### Helpers
|
||||
|
||||
#### [jecs_ob](https://github.com/Ukendio/jecs/blob/main/addons/ob.luau)
|
||||
Observers & Monitors for queries
|
||||
|
||||
### [hammer](https://github.com/Mark-Marks/hammer)
|
||||
A set of utilities for Jecs
|
||||
|
||||
### Schedulers
|
||||
|
||||
#### [lockstep scheduler](https://gist.github.com/1Axen/6d4f78b3454cf455e93794505588354b)
|
||||
A simple fixed step system scheduler.
|
||||
|
||||
#### [rubine](https://github.com/Mark-Marks/rubine)
|
||||
An ergonomic, runtime agnostic scheduler for Jecs
|
||||
|
||||
#### [jam](https://github.com/revvy02/Jam)
|
||||
Provides hooks and a scheduler that implements jabby and a topographical runtime
|
||||
|
||||
#### [planck](https://github.com/YetAnotherClown/planck)
|
||||
An agnostic scheduler inspired by Bevy and Flecs, with core features including phases, pipelines, run conditions, and startup systems.
|
||||
Planck also provides plugins for Jabby, Matter Hooks, and more.
|
||||
|
||||
### Networking
|
||||
|
||||
#### [feces](https://github.com/NeonD00m/feces)
|
||||
A generalized replication system for jecs
|
||||
|
||||
### Input
|
||||
|
||||
#### [Axis](https://github.com/NeonD00m/axis)
|
||||
An agnostic, simple and versatile input library for ECS
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
# Examples
|
||||
|
||||
This folder contains code examples for the Luau/Typescript APIs.
|
||||
|
||||
## Run with Luau
|
||||
To run the examples with Luau, run the following commands from the root of the repository:
|
||||
|
||||
```sh
|
||||
cd examples/luau
|
||||
luau path/to/file.luau
|
||||
```
|
||||
33
howto/001_hello_world.luau
Executable file
33
howto/001_hello_world.luau
Executable file
|
|
@ -0,0 +1,33 @@
|
|||
--[[
|
||||
It all has to start somewhere. A world stores entities and their components,
|
||||
and manages them. This tour will reference it for every operation.
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
--[[
|
||||
You can declare component ids with specific types with this format:
|
||||
|
||||
ComponentId = world:component() :: jecs.Id<Type>
|
||||
]]
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
|
||||
-- Creates an empty entity and returns its handle
|
||||
local entity = world:entity()
|
||||
|
||||
-- You can give entities data using `world:set()`. The type solver will
|
||||
-- enforce that the data you assign to the entity will match the type
|
||||
-- of the component id.
|
||||
world:set(entity, Position, vector.create(1, 2, 3))
|
||||
|
||||
-- If you want the Entity's Position, you can look it up with the component ID.
|
||||
-- It will return the value with the component's type coalesced with "nil"
|
||||
-- because the entity's type is only known at runtime.
|
||||
print(`Entity's Position is {world:get(entity, Position)}`)
|
||||
|
||||
--[[
|
||||
To run it:
|
||||
luau 001_hello_world.luau
|
||||
]]
|
||||
110
howto/002_entities.luau
Executable file
110
howto/002_entities.luau
Executable file
|
|
@ -0,0 +1,110 @@
|
|||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
--[[
|
||||
Entities represent things in a game. In a game there may be entities of
|
||||
characters, buildings, projectiles, particle effects etc.
|
||||
|
||||
By itself, an entity is just an unique entity identifier without any data.
|
||||
An entity identifier contains information about the entity itself and its generation.
|
||||
]]
|
||||
|
||||
|
||||
-- Creates a new entity with no components and returns its identifier
|
||||
local entity = world:entity()
|
||||
print(entity)
|
||||
|
||||
-- The entity member function also accepts an overload that allows you to create
|
||||
-- an entity with a desired id which bypasses the entity range.
|
||||
world:entity(42)
|
||||
|
||||
--[[
|
||||
|
||||
The entity ID will have a corresponding entity
|
||||
record that essentially just keeps indices into arrays of data.
|
||||
The format of the entity record is:
|
||||
|
||||
record: {
|
||||
row: number,
|
||||
}
|
||||
|
||||
--]]
|
||||
|
||||
-- You can retrieve an entity's record by using one of jecs' functions:
|
||||
|
||||
local record = jecs.record(world, entity)
|
||||
print(record)
|
||||
|
||||
--[[
|
||||
|
||||
Underneath the ECS the entity ID and its record will be stored in two separate arrays.
|
||||
A dense array and a sparse array. Other than the fact that there is
|
||||
two arrays is an unimportant implementation detail.
|
||||
We just use these distinct terms to differentiate tnem. The format is:
|
||||
|
||||
dense_array: { u53 }
|
||||
sparse_array: { [u24]: record }
|
||||
|
||||
The entity ID that you operate with is an element in the dense array with
|
||||
the u53 number type. In reality, there is no such thing as a u53 number
|
||||
type. In luau it is actually all just doubles (IEEE-754 f64).
|
||||
|
||||
However the size of the integer mantissa in a double is 53 bits, so it
|
||||
can represent integers with full precision up to 2^53.
|
||||
|
||||
As a refresher here is the IEEE-754 f64 (double) bit layout:
|
||||
|
||||
bit index: 63 52 51 0
|
||||
| | | |
|
||||
v v v v
|
||||
+---------+---------------+-------------------------------+
|
||||
| sign | exponent | mantissa / fraction |
|
||||
| (1 bit) | (11 bits) | (52 bits) |
|
||||
+---------+---------------+-------------------------------+
|
||||
|
||||
Entity IDs use 48 bits which is well within the range for the mantissa.
|
||||
This is useful to know because it allows the ECS to put a lot of information
|
||||
in this opaque ID number such as the index into the sparse_array and a generation.
|
||||
|
||||
A generation is a number that increments everytime an entity index is
|
||||
reused. By embedding this counter into the entity ID, any stale handle
|
||||
referring to a previous entity of that index becomes invalid.
|
||||
Because programmers are not perfect and often forget about dangling pointers
|
||||
as a result of storing and referencing entities outside of the ECS.
|
||||
|
||||
If the index 10 has been used for an entity, dies, and gets reused.
|
||||
The new entity becomes index 10, generation 2.
|
||||
|
||||
The layout of the ID itself is:
|
||||
|
||||
[ 47 ........ 24 ][ 23 ........ 0 ]
|
||||
| generation | index |
|
||||
| (24 bits) | (24 bits) |
|
||||
|
||||
The index is used to lookup the corresponding record for the entity such as:
|
||||
|
||||
record = sparse_array[downcast(u24)(dense_array[n])]
|
||||
--]]
|
||||
|
||||
-- It is possible to read the index and the generation of an entity ID
|
||||
-- using the public API with the following:
|
||||
|
||||
local ECS_ID = jecs.ECS_ID
|
||||
local ECS_GENERATION = jecs.ECS_GENERATION
|
||||
|
||||
local index = ECS_ID(entity)
|
||||
local generation = ECS_GENERATION(entity)
|
||||
|
||||
print(`Entity's index and generation are {index} and {generation} respectively`)
|
||||
|
||||
-- A notable detail about entity IDs is that they can become very large
|
||||
-- as the generation increases. This is because the bits
|
||||
-- further to the left represent much larger powers of two.
|
||||
|
||||
world:delete(entity)
|
||||
|
||||
local recycled_entity = world:entity()
|
||||
|
||||
print(`This is a huuuuge number {recycled_entity}`)
|
||||
print(`The recycled entity's generation incremented to {ECS_GENERATION(recycled_entity)} `)
|
||||
print(`However it retains the old index at {ECS_ID(recycled_entity)}`)
|
||||
139
howto/003_components.luau
Executable file
139
howto/003_components.luau
Executable file
|
|
@ -0,0 +1,139 @@
|
|||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
--[[
|
||||
A component is something that is added to an entity. Components can simply
|
||||
tag an entity ("this entity is an Npc"), attach data to an entity ("this entity
|
||||
is at Position Vector3.new(10, 20, 30)") and create relationships between
|
||||
entities ("bob Likes alice") that may also contain data ("bob Eats 10 apples").
|
||||
]]
|
||||
|
||||
-- Create a component with a type
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Health = world:component() :: jecs.Id<number>
|
||||
|
||||
--[[
|
||||
Components are keys to ECS storage columns. Think of the ECS storage as
|
||||
a table where:
|
||||
- Rows are entities
|
||||
- Columns are components
|
||||
- Cells are the component data for that entity
|
||||
|
||||
When you create a component, you're creating a key that you'll use to
|
||||
index into the storage. The component ID is what tells the ECS "I want
|
||||
to access the Position column" or "I want to access the Health column".
|
||||
|
||||
The component ID is just a number, but it's been registered with the world.
|
||||
This registration is what allows the ECS to know about the component and
|
||||
allocate storage for it when entities use it.
|
||||
]]
|
||||
|
||||
print(`Position component ID: {Position}`)
|
||||
print(`Health component ID: {Health}`)
|
||||
|
||||
--[[
|
||||
If you try to use a number as a component ID that has not been registered,
|
||||
the ECS will throw an error at runtime because the ID is not known to the
|
||||
World. You must create components using world:component() before you can
|
||||
use them.
|
||||
]]
|
||||
|
||||
local entity = world:entity()
|
||||
|
||||
--[[
|
||||
world:set(entity, component, value)
|
||||
|
||||
Sets the value of a component for an entity. This is how you store data
|
||||
in the ECS columns. The component ID acts as the column index, and the
|
||||
entity acts as the row index.
|
||||
|
||||
If the entity doesn't already have the component, set() will add it
|
||||
automatically. If it does have the component, set() will update the
|
||||
existing value.
|
||||
|
||||
The type system enforces that the value you provide matches the component's
|
||||
type. This prevents type errors at compile time (if using a type checker).
|
||||
]]
|
||||
|
||||
-- Set initial values
|
||||
world:set(entity, Position, vector.create(10, 20, 30))
|
||||
world:set(entity, Health, 100)
|
||||
|
||||
-- Update values (set works for both adding and updating)
|
||||
world:set(entity, Position, vector.create(40, 50, 60))
|
||||
world:set(entity, Health, 50)
|
||||
|
||||
--[[
|
||||
world:get(entity, component)
|
||||
|
||||
Retrieves the value of a component from an entity. This is how you read
|
||||
data from the ECS columns. The component ID tells the ECS which column
|
||||
to look in, and the entity tells it which row.
|
||||
|
||||
The return type is `T?` (T or nil), not just `T`. This is because the
|
||||
entity might not have the component, or the entity might have been deleted.
|
||||
You should always handle the nil case.
|
||||
|
||||
In practice, you'll often use assert() if you know the component should
|
||||
exist, or check for nil if it might not exist.
|
||||
]]
|
||||
|
||||
-- Get component values
|
||||
local pos = world:get(entity, Position)
|
||||
local health = world:get(entity, Health)
|
||||
|
||||
print(`Entity position: {pos}`)
|
||||
print(`Entity health: {health}`)
|
||||
|
||||
-- Handle the nil case
|
||||
local maybe_pos = world:get(entity, Position)
|
||||
if maybe_pos then
|
||||
print(`Position exists: {maybe_pos}`)
|
||||
else
|
||||
print("Entity doesn't have Position")
|
||||
end
|
||||
|
||||
-- Or use assert if you know it should exist
|
||||
local pos_assert = assert(world:get(entity, Position))
|
||||
print(`Position (asserted): {pos_assert}`)
|
||||
|
||||
--[[
|
||||
world:remove(entity, component)
|
||||
|
||||
Removes a component from an entity. This removes the data from the storage
|
||||
column for that entity. The entity will no longer have that component.
|
||||
|
||||
If the entity doesn't have the component, remove() does nothing (it's
|
||||
idempotent). This makes it safe to call remove() multiple times.
|
||||
|
||||
Note: remove() only removes the component, it doesn't delete the entity.
|
||||
Use world:delete() if you want to delete the entire entity.
|
||||
]]
|
||||
|
||||
-- Remove a component
|
||||
world:remove(entity, Health)
|
||||
|
||||
-- Now Health is gone
|
||||
print(`Health after remove: {world:get(entity, Health)}`) -- nil
|
||||
|
||||
-- Position is still there
|
||||
print(`Position after removing Health: {world:get(entity, Position)}`) -- still has value
|
||||
|
||||
-- Removing a component that doesn't exist does nothing
|
||||
world:remove(entity, Health) -- Safe to call again, does nothing
|
||||
|
||||
--[[
|
||||
Components are keys to storage columns. When you use set(), get(), or remove(),
|
||||
you're using the component ID to index into the ECS storage:
|
||||
|
||||
set(entity, Position, value) -> storage[Position][entity] = value
|
||||
get(entity, Position) -> return storage[Position][entity]
|
||||
remove(entity, Position) -> storage[Position][entity] = nil
|
||||
|
||||
This is the fundamental abstraction of the ECS: components are column keys,
|
||||
entities are row keys, and the storage is a two-dimensional table.
|
||||
|
||||
In reality, the storage is more sophisticated (it uses archetypes for
|
||||
efficiency), but this mental model is useful for understanding how the
|
||||
APIs work.
|
||||
]]
|
||||
50
howto/004_tags.luau
Executable file
50
howto/004_tags.luau
Executable file
|
|
@ -0,0 +1,50 @@
|
|||
local jecs = require("@jecs")
|
||||
|
||||
--[[
|
||||
Tags are components without data. They are used to mark or categorize entities
|
||||
without storing any associated values. Think of them as boolean flags that
|
||||
can be added or removed from entities.
|
||||
|
||||
A tag takes zero bytes of storage per entity. More importantly,
|
||||
tags enable a different mental model. When you see a tag on an
|
||||
entity, you know it's just a marker and there's no data to read or write.
|
||||
|
||||
Tags are entities that do not have the builtin jecs.Component trait which
|
||||
tells the ECS that this ID doesn't cannot store any data, it is just a marker.
|
||||
]]
|
||||
|
||||
--[[
|
||||
There are two ways to create tags:
|
||||
|
||||
1. Using jecs.tag() - preregister a tag entity which will be allocated when you create the world.
|
||||
2. Using world:entity() - creates a regular entity id
|
||||
|
||||
The first method is the "proper" way to create tags but it hinges upon that
|
||||
you do remember to create the world after declaring all of your
|
||||
components/tags. This is a good practice because it is harder to mess up the
|
||||
offset of your component range, ensuring a stable type id.
|
||||
|
||||
More on this is discussed in 011_preregistering_components.luau
|
||||
]]
|
||||
|
||||
local Dead = jecs.tag()
|
||||
|
||||
-- Creating the world after the components to ensure they get allocated.
|
||||
local world = jecs.world()
|
||||
|
||||
--
|
||||
-- Tags are added using world:add(entity, component).
|
||||
-- You cannot use world:set() with tags
|
||||
-- because tags don't store data.
|
||||
|
||||
local entity = world:entity()
|
||||
|
||||
world:add(entity, Dead) -- Adds the tag
|
||||
|
||||
print(world:has(entity, Dead)) -- true
|
||||
|
||||
-- Tags are removed using world:remove(entity, component)
|
||||
|
||||
world:remove(entity, Dead)
|
||||
|
||||
print(world:has(entity, Dead)) -- false
|
||||
12
howto/005_entity_singletons.luau
Executable file
12
howto/005_entity_singletons.luau
Executable file
|
|
@ -0,0 +1,12 @@
|
|||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
-- Singletons are components for which only a single instance exists on the world.
|
||||
-- They can be accessed on the world directly and do not require providing
|
||||
-- an entity. Singletons are useful for global game resources, such as game state,
|
||||
-- a handle to a physics engine or a network socket.
|
||||
|
||||
local TimeOfDay = world:component() :: jecs.Id<number>
|
||||
world:set(TimeOfDay, TimeOfDay, 5)
|
||||
local t = world:get(TimeOfDay, TimeOfDay)
|
||||
print(`The time of day is {t}`)
|
||||
35
howto/010_how_components_works.luau
Executable file
35
howto/010_how_components_works.luau
Executable file
|
|
@ -0,0 +1,35 @@
|
|||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
--[[
|
||||
In an ECS, components need to be uniquely identified. In Jecs this is done
|
||||
by making each component its own unique entity.
|
||||
|
||||
If a game has a component Position and Velocity, there will be two entities,
|
||||
one for each component. Component entities can be distinguished from "regular"
|
||||
entities as they have a Component component trait.
|
||||
|
||||
This might seem odd at first. Why make components entities? The answer
|
||||
is uniformity. If components are entities, then all the APIs that work
|
||||
on entities also work on components. You can set metadata on components,
|
||||
you can query for components, you can create relationships between components.
|
||||
Everything is just entities, and entities can have components, so components
|
||||
can have components too.
|
||||
]]
|
||||
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
world:set(Position, jecs.Name, "Position") -- Using regular APIs to set metadata on component entities!
|
||||
|
||||
print(`{world:get(Position, jecs.Name)} is a Component: {world:has(Position, jecs.Component)}`)
|
||||
|
||||
-- Component IDs occupy the range 1-256.
|
||||
|
||||
-- This partitioning comes at a cost, you can only linearize the component IDs
|
||||
-- up to 256. This is usually sufficient.
|
||||
|
||||
-- Otherwise you must either patch jecs itself to increment the "HI_COMPONENT_ID"
|
||||
-- or create your own entities and then add the jecs.Component trait.
|
||||
|
||||
local high_comp_id = world:entity()
|
||||
world:add(high_comp_id, jecs.Component)
|
||||
21
howto/011_preregistering_components.luau
Executable file
21
howto/011_preregistering_components.luau
Executable file
|
|
@ -0,0 +1,21 @@
|
|||
--[[
|
||||
By default, components being registered on runtime is useful for how dynamic
|
||||
it can be. But, sometimes being able to register components without having
|
||||
the world instance is useful.
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
|
||||
local Position = jecs.component() :: jecs.Id<vector>
|
||||
|
||||
jecs.world() -- Position gets registered here
|
||||
|
||||
--[[
|
||||
However, if you try to set metadata, you will find that this doesn't work
|
||||
without the world instance. Instead, jecs offers a meta member function
|
||||
that can forward declare its metadata.
|
||||
]]
|
||||
|
||||
jecs.meta(Position, jecs.Name, "Position")
|
||||
|
||||
jecs.world() -- Position gets registered here with its name "Position"
|
||||
94
howto/013_pairs.luau
Executable file
94
howto/013_pairs.luau
Executable file
|
|
@ -0,0 +1,94 @@
|
|||
local jecs = require("@jecs")
|
||||
local pair = jecs.pair
|
||||
local world = jecs.world()
|
||||
|
||||
local pair_first = jecs.pair_first
|
||||
local pair_second = jecs.pair_second
|
||||
local is_pair = jecs.IS_PAIR
|
||||
|
||||
local Likes = world:entity()
|
||||
local Owns = world:component() :: jecs.Id<{ purchase_date: string }>
|
||||
local alice = world:entity()
|
||||
local car = world:entity()
|
||||
|
||||
--[[
|
||||
A pair is an ID that encodes two elements. Pairs, like components, can be
|
||||
added to entities and are the foundation for Relationships.
|
||||
|
||||
The elements of a pair are allowed to be wildcards. When a query pair returns
|
||||
an Any type wildcard, the query returns at most a single matching pair on
|
||||
an entity.
|
||||
|
||||
Pairs encode two entity IDs into a single 53-bit ID. This encoding allows
|
||||
the ECS to treat pairs the same way as regular component IDs at the storage
|
||||
level, while still being able to decode them back into their constituent
|
||||
parts when needed.
|
||||
|
||||
The pair encoding uses the upper bits of the 53-bit ID space. Specifically,
|
||||
pairs have an offset (ECS_PAIR_OFFSET = 2^48) added to them, which makes
|
||||
them larger than any possible regular entity ID. This allows the ECS to
|
||||
quickly distinguish pairs from regular entities by checking if the ID is
|
||||
greater than the pair offset.
|
||||
]]
|
||||
|
||||
|
||||
--[[
|
||||
Creating pairs
|
||||
|
||||
You create a pair using the pair() function. It takes two entities:
|
||||
- The first entity is the relationship/predicate (e.g., "Likes", "Owns")
|
||||
- The second entity is the target/object (e.g., "alice", "car")
|
||||
]]
|
||||
|
||||
local likes_alice_pair = pair(Likes, alice)
|
||||
print(`Pair ID: {likes_alice_pair}`)
|
||||
|
||||
local owns_car_pair = pair(Owns, car)
|
||||
print(`Pair ID: {owns_car_pair}`)
|
||||
|
||||
local entity = world:entity()
|
||||
|
||||
-- Pairs can be used just like component IDs. You can add them to entities,
|
||||
-- query for them, and store data with them.
|
||||
world:add(entity, pair(Likes, alice))
|
||||
print(`entity likes alice {world:has(entity, pair(Likes, alice))}`)
|
||||
|
||||
world:set(entity, pair(Owns, car), { purchase_date = "2024-01-01" })
|
||||
|
||||
local ownership_data = world:get(entity, pair(Owns, car))
|
||||
assert(ownership_data)
|
||||
print(`Ownership data: {ownership_data.purchase_date}`)
|
||||
|
||||
-- You can check if an ID is a pair using jecs.IS_PAIR(). This is useful
|
||||
-- when you're working with IDs and need to know if they're pairs or
|
||||
-- regular entities.
|
||||
|
||||
local regular_id = world:entity()
|
||||
local pair_id = pair(Likes, alice)
|
||||
|
||||
print(is_pair(regular_id))
|
||||
print(is_pair(pair_id))
|
||||
|
||||
-- If you have a pair ID, you can extract the first and second elements
|
||||
-- using jecs.ECS_PAIR_FIRST() and jecs.ECS_PAIR_SECOND(). However, these
|
||||
-- return the raw entity IDs, so you typically want to use world:target()
|
||||
-- instead, which handles alive entity resolution.
|
||||
|
||||
|
||||
local p = pair(Likes, alice)
|
||||
local first = pair_first(world, p)
|
||||
local second = pair_second(world, p)
|
||||
|
||||
print(`Pair ({first}, {second})`)
|
||||
|
||||
-- Pairs can have components as targets, not just entities. This is useful
|
||||
-- for relationships like "has Position at (0, 0, 0)" or "has Health of 100".
|
||||
|
||||
-- However, this is less common. Typically, you use pairs for entity-to-entity
|
||||
-- relationships, and regular components for entity-to-data relationships.
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Begin = world:entity()
|
||||
local End = world:entity()
|
||||
world:set(entity, pair(Begin, Position), vector.create(0, 0, 0))
|
||||
world:set(entity, pair(End, Position), vector.create(10, 20, 30))
|
||||
52
howto/020_queries.luau
Executable file
52
howto/020_queries.luau
Executable file
|
|
@ -0,0 +1,52 @@
|
|||
--[[
|
||||
Queries enable games to quickly find entities that satisfies provided conditions.
|
||||
In jecs, queries can do anything from returning entities that match a simple
|
||||
list of components, to matching against entity graphs.
|
||||
|
||||
Some of the features of Jecs queries are:
|
||||
- Queries have support for relationships pairs which allow for matching against
|
||||
entity graphs without having to build complex data structures for it.
|
||||
- Queries support filters such as query:with(...) if entities are required to
|
||||
have the components but you don't actually care about components value.
|
||||
And query:without(...) which selects entities without the components.
|
||||
- Queries can be drained or reset on when called, which lets you choose iterator behaviour.
|
||||
- Queries can be called with any ID, including entities created dynamically,
|
||||
this is useful for pairs.
|
||||
- Queries are already fast but can be further inlined via query:archetypes()
|
||||
for maximum performance to eliminate function call overhead which is roughly
|
||||
60-80% of the cost for iteration.
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Velocity = world:component() :: jecs.Id<vector>
|
||||
|
||||
for entity, pos, vel in world:query(Position, Velocity) do
|
||||
-- Process entities with both Position and Velocity
|
||||
end
|
||||
|
||||
--[[
|
||||
A component is any single ID that can be added to an entity. This includes
|
||||
tags and regular entities, which are IDs that do not have the builtin Component
|
||||
component. To match a query, an entity must have all the requested components.
|
||||
]]
|
||||
|
||||
local e1 = world:entity()
|
||||
world:add(e1, Position)
|
||||
|
||||
local e2 = world:entity()
|
||||
world:add(e2, Position)
|
||||
world:add(e2, Velocity)
|
||||
|
||||
local e3 = world:entity()
|
||||
world:add(e3, Position)
|
||||
world:add(e3, Velocity)
|
||||
local Mass = world:component()
|
||||
world:add(e3, Mass)
|
||||
|
||||
-- Only entities e2 and e3 match the query Position, Velocity
|
||||
for entity, pos, vel in world:query(Position, Velocity) do
|
||||
print(`Entity {entity} has Position and Velocity`)
|
||||
end
|
||||
37
howto/021_query_operators.luau
Executable file
37
howto/021_query_operators.luau
Executable file
|
|
@ -0,0 +1,37 @@
|
|||
--[[
|
||||
Filters are extensions to queries which allow you to select entities from
|
||||
a more complex pattern but you don't actually care about the component values.
|
||||
|
||||
The following filters are supported by queries:
|
||||
|
||||
| Identifier | Description |
|
||||
| ---------- | ----------------------------------- |
|
||||
| With | Must match with all terms. |
|
||||
| Without | Must not match with provided terms. |
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Velocity = world:component() :: jecs.Id<vector>
|
||||
local Walking = world:component()
|
||||
|
||||
-- Query with filter: entities that have Position and Velocity, but we don't
|
||||
-- need the values, just want to know they exist
|
||||
world:query(Position, Velocity)
|
||||
:with(Walking) -- Must also have Walking tag
|
||||
:without(Velocity) -- Can specify components to exclude
|
||||
|
||||
-- Wildcards
|
||||
--[[
|
||||
Jecs currently only supports the Any type of wildcards which a single result
|
||||
for the first component that it matches.
|
||||
|
||||
When using the Any type wildcard it is undefined which component will be
|
||||
matched, as this can be influenced by other parts of the query. It is guaranteed
|
||||
that iterating the same query twice on the same dataset will produce the same result.
|
||||
|
||||
If you want to iterate multiple targets for the same relation on a pair,
|
||||
then use world:target()
|
||||
]]
|
||||
84
howto/022_query_caching.luau
Executable file
84
howto/022_query_caching.luau
Executable file
|
|
@ -0,0 +1,84 @@
|
|||
--[[
|
||||
Understanding the basic architecture of queries helps to make the right
|
||||
tradeoffs when using queries in games. The biggest impact on query performance
|
||||
is whether a query is cached or not. This section goes over what caching is,
|
||||
how it can be used and when it makes sense to use it.
|
||||
|
||||
Caching: what is it?
|
||||
|
||||
Jecs is an archetype ECS, which means that entities with exactly the same
|
||||
components are grouped together in an "archetype". Archetypes are created
|
||||
on the fly whenever a new component combination is created in the ECS.
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Velocity = world:component() :: jecs.Id<vector>
|
||||
local Mass = world:component() :: jecs.Id<number>
|
||||
|
||||
local e1 = world:entity()
|
||||
world:set(e1, Position, vector.create(10, 20, 30)) -- create archetype [Position]
|
||||
world:set(e1, Velocity, vector.create(1, 2, 3)) -- create archetype [Position, Velocity]
|
||||
|
||||
local e2 = world:entity()
|
||||
world:set(e2, Position, vector.create(10, 20, 30)) -- archetype [Position] already exists
|
||||
world:set(e2, Velocity, vector.create(1, 2, 3)) -- archetype [Position, Velocity] already exists
|
||||
world:set(e2, Mass, 100) -- create archetype [Position, Velocity, Mass]
|
||||
|
||||
-- e1 is now in archetype [Position, Velocity]
|
||||
-- e2 is now in archetype [Position, Velocity, Mass]
|
||||
|
||||
--[[
|
||||
Archetypes are important for queries. Since all entities in an archetype have
|
||||
the same components, and a query matches entities with specific components,
|
||||
a query can often match entire archetypes instead of individual entities.
|
||||
This is one of the main reasons why queries in an archetype ECS are fast.
|
||||
|
||||
The second reason that queries in an archetype ECS are fast is that they are
|
||||
cheap to cache. While an archetype is created for each unique component
|
||||
combination, games typically only use a finite set of component combinations
|
||||
which are created quickly after game assets are loaded.
|
||||
|
||||
This means that instead of searching for archetypes each time a query is
|
||||
evaluated, a query can instead cache the list of matching archetypes. This
|
||||
is a cheap cache to maintain: even though entities can move in and out of
|
||||
archetypes, the archetypes themselves are often stable.
|
||||
|
||||
If none of that made sense, the main thing to remember is that a cached query
|
||||
does not actually have to search for entities. Iterating a cached query just
|
||||
means iterating a list of prematched results, and this is really, really fast.
|
||||
|
||||
Tradeoffs
|
||||
|
||||
Jecs has both cached and uncached queries. If cached queries are so fast,
|
||||
why even bother with uncached queries? There are four main reasons:
|
||||
|
||||
- Cached queries are really fast to iterate, but take more time to create
|
||||
because the cache must be initialized first.
|
||||
- Cached queries add overhead to archetype creation/deletion, as these changes
|
||||
have to get propagated to caches.
|
||||
- While caching archetypes is fast, some query features require matching
|
||||
individual entities, which are not efficient to cache (and aren't cached).
|
||||
|
||||
As a rule of thumb, if you have a query that is evaluated each frame (as is
|
||||
typically the case with systems), they will benefit from being cached.
|
||||
If you need to create a query ad-hoc, an uncached query makes more sense.
|
||||
|
||||
Ad-hoc queries are often necessary when a game needs to find entities that
|
||||
match a condition that is only known at runtime, for example to find all
|
||||
child entities for a specific parent.
|
||||
]]
|
||||
|
||||
-- Uncached query (default)
|
||||
for entity, pos, vel in world:query(Position, Velocity) do
|
||||
-- Process entities
|
||||
end
|
||||
|
||||
-- Cached query (faster for repeated use)
|
||||
local cached_query = world:query(Position, Velocity):cached()
|
||||
for entity, pos, vel in cached_query do
|
||||
-- Process entities - this is faster for repeated iterations
|
||||
end
|
||||
|
||||
84
howto/030_archetypes.luau
Executable file
84
howto/030_archetypes.luau
Executable file
|
|
@ -0,0 +1,84 @@
|
|||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
|
||||
--[[
|
||||
When an entity moves to a new archetype, several things happen:
|
||||
|
||||
1. The entity is removed from the old archetype's entity list
|
||||
2. Component data is copied from old columns to new columns (if the component
|
||||
exists in both archetypes)
|
||||
3. The entity is added to the new archetype's entity list
|
||||
4. The entity's record is updated to point to the new archetype
|
||||
5. The entity's row index is updated to its position in the new archetype
|
||||
|
||||
This movement is what makes adding/removing components relatively expensive
|
||||
compared to just setting component values. But it's necessary to maintain
|
||||
the invariant that all entities in an archetype have exactly the same
|
||||
component set.
|
||||
]]
|
||||
|
||||
|
||||
|
||||
-- When you create an entity, it starts with no components. All entities with
|
||||
-- no components belong to the ROOT_ARCHETYPE.
|
||||
-- This is the starting point for all entities.
|
||||
|
||||
local e1 = world:entity()
|
||||
world:set(e1, Position, vector.create(10, 20, 30))
|
||||
|
||||
--[[
|
||||
Archetypes are the fundamental storage unit in an archetypal ECS.
|
||||
An archetype represents a unique combination of components.
|
||||
All entities with exactly the same set of components belong to the same archetype.
|
||||
|
||||
When you add a component to an entity, the entity must move from its current
|
||||
archetype to a new archetype that includes the new component.
|
||||
This transition process includes several operations:
|
||||
|
||||
1. The entity is removed from the old archetype's entity list
|
||||
2. Component data is copied from old columns to new columns (if the component
|
||||
exists in both archetypes)
|
||||
3. The entity is added to the new archetype's entity list
|
||||
4. The entity's record is updated to point to the new archetype
|
||||
5. The entity's row index is updated to its position in the new archetype
|
||||
If that archetype
|
||||
doesn't exist yet, it must be created.
|
||||
|
||||
When an Archetype is created, it performs several operations:
|
||||
|
||||
1. Allocates a new archetype ID (increments max_archetype_id)
|
||||
2. Creates storage columns
|
||||
3. Registers the archetype
|
||||
4. Updates component records
|
||||
5. Propagates it to cached queries that needs to update its list of archetyps
|
||||
|
||||
Archetypes are connected in a graph structure. Each archetype has edges that
|
||||
point to other archetypes you can reach by adding or removing components.
|
||||
|
||||
For example:
|
||||
- ROOT_ARCHETYPE has an edge for Position -> [Position]
|
||||
- [Position] has an edge for Velocity -> [Position, Velocity]
|
||||
- [Position] has an edge (backwards) for Position -> ROOT_ARCHETYPE
|
||||
|
||||
This graph is cached. When you add a component, the ECS first checks if
|
||||
there's already an edge from the current archetype for that component.
|
||||
If the edge exists, it uses the cached archetype.
|
||||
|
||||
If an edge doesn't exist it will do the following operations:
|
||||
a. Create a new component list: [Position, Velocity] (sorted)
|
||||
b. Hash it to get the type string
|
||||
c. Check if archetype exists (might have been created by another entity)
|
||||
d. If not, create it
|
||||
e. Cache the edge in both directions
|
||||
|
||||
This caching is what makes archetype transitions fast. Instead of searching
|
||||
through all archetypes every time, you just follow the graph edges.
|
||||
|
||||
The edge caching happens in both directions:
|
||||
- [Position] -> [Position, Velocity] (for adding Velocity)
|
||||
- [Position, Velocity] -> [Position] (for removing Velocity)
|
||||
|
||||
]]
|
||||
48
howto/040_fragmentation.luau
Executable file
48
howto/040_fragmentation.luau
Executable file
|
|
@ -0,0 +1,48 @@
|
|||
local jecs = require("@jecs")
|
||||
local pair = jecs.pair
|
||||
local world = jecs.world()
|
||||
|
||||
local Likes = world:component()
|
||||
|
||||
--[[
|
||||
Fragmentation is a property of archetype-based ECS implementations where entities
|
||||
are spread out over more archetypes as the number of different component combinations
|
||||
increases. The overhead of fragmentation is visible in two areas:
|
||||
- Archetype creation
|
||||
- Queries (queries have to match & iterate more archetypes)
|
||||
|
||||
Games that make extensive use of relationships might observe high levels of
|
||||
fragmentation, as relationships can introduce many different combinations of
|
||||
components. While the Jecs storage is optimized for supporting large amounts
|
||||
(hundreds of thousands) of archetypes, fragmentation is a factor to consider
|
||||
when using relationships.
|
||||
|
||||
To improve the speed of evaluating queries, Jecs has indices that store all
|
||||
archetypes for a given component ID. Whenever a new archetype is created, it is
|
||||
registered with the indices for the IDs the archetype has, including IDs for
|
||||
relationship pairs.
|
||||
|
||||
While registering an archetype for a relationship index is not more expensive
|
||||
than registering an archetype for a regular index, an archetype with relationships
|
||||
has to also register itself with the appropriate wildcard indices for its
|
||||
relationships. For example, an archetype with relationship pair(Likes, Apples)
|
||||
registers itself with the pair(Likes, Apples), pair(Likes, jecs.Wildcard) and
|
||||
pair(jecs.Wildcard, Apples) indices. For this reason, creating new archetypes
|
||||
with relationships has a higher overhead than an archetype without relationships.
|
||||
]]
|
||||
|
||||
local alice = world:entity()
|
||||
local bob = world:entity()
|
||||
local charlie = world:entity()
|
||||
|
||||
local e1 = world:entity()
|
||||
world:add(e1, pair(Likes, alice)) -- Creates archetype [pair(Likes, alice)]
|
||||
|
||||
local e2 = world:entity()
|
||||
world:add(e2, pair(Likes, bob)) -- Creates archetype [pair(Likes, bob)]
|
||||
|
||||
local e3 = world:entity()
|
||||
world:add(e3, pair(Likes, charlie)) -- Creates archetype [pair(Likes, charlie)]
|
||||
|
||||
-- Each different target creates a new archetype, leading to fragmentation
|
||||
-- This is why relationships can increase archetype count significantly
|
||||
207
howto/041_entity_relationships.luau
Executable file
207
howto/041_entity_relationships.luau
Executable file
|
|
@ -0,0 +1,207 @@
|
|||
--[[
|
||||
Relationships makes it possible to describe entity graphs natively in ECS.
|
||||
|
||||
Adding/removing relationships is similar to adding/removing regular components,
|
||||
with as difference that instead of a single component id, a relationship adds
|
||||
a pair of two things to an entity. In this pair, the first element represents
|
||||
the relationship (e.g. "Eats"), and the second element represents the relationship
|
||||
target (e.g. "Apples").
|
||||
|
||||
Relationships can be used to describe many things, from hierarchies to inventory
|
||||
systems to trade relationships between players in a game.
|
||||
|
||||
Definitions:
|
||||
- Id: An id that can be added and removed
|
||||
- Component: Id with a single element (same as an entity id)
|
||||
- Relationship: Used to refer to first element of a pair
|
||||
- Target: Used to refer to second element of a pair
|
||||
- Source: Entity to which an id is added
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local pair = jecs.pair
|
||||
local world = jecs.world()
|
||||
|
||||
local Eats = world:component() :: jecs.Id<{ amount: number }>
|
||||
local Likes = world:component()
|
||||
local Apples = world:entity()
|
||||
local bob = world:entity()
|
||||
local alice = world:entity()
|
||||
|
||||
-- Add relationships
|
||||
world:add(bob, pair(Eats, Apples))
|
||||
world:add(bob, pair(Likes, alice))
|
||||
world:add(alice, pair(Likes, bob))
|
||||
|
||||
-- Test if entity has a relationship pair
|
||||
print(world:has(bob, pair(Eats, Apples))) -- true
|
||||
|
||||
-- Test if entity has a relationship wildcard
|
||||
print(world:has(bob, pair(Eats, jecs.Wildcard))) -- true
|
||||
|
||||
--[[
|
||||
Querying for relationship targets
|
||||
|
||||
One of the most common operations with relationships is finding all entities
|
||||
that have a relationship with a specific target. For example, finding all
|
||||
children of a parent, or finding all entities that like a specific person.
|
||||
]]
|
||||
|
||||
-- Find all entities with a specific pair (all entities that eat apples)
|
||||
for entity in world:query(pair(Eats, Apples)) do
|
||||
print(`Entity {entity} eats apples`)
|
||||
end
|
||||
|
||||
-- Find all entities that like alice
|
||||
for entity in world:query(pair(Likes, alice)) do
|
||||
print(`Entity {entity} likes alice`)
|
||||
end
|
||||
|
||||
--[[
|
||||
Querying for children of a parent
|
||||
|
||||
The built-in ChildOf relationship is commonly used for hierarchies. You can
|
||||
query for all children of a specific parent entity.
|
||||
]]
|
||||
|
||||
local ChildOf = jecs.ChildOf
|
||||
local parent = world:entity()
|
||||
local child1 = world:entity()
|
||||
local child2 = world:entity()
|
||||
|
||||
world:add(child1, pair(ChildOf, parent))
|
||||
world:add(child2, pair(ChildOf, parent))
|
||||
|
||||
-- Find all children of a specific parent
|
||||
for child in world:query(pair(ChildOf, parent)) do
|
||||
print(`Entity {child} is a child of parent {parent}`)
|
||||
end
|
||||
|
||||
--[[
|
||||
Querying with wildcards and getting targets
|
||||
|
||||
When you query with a wildcard, you can use world:target() to get the
|
||||
actual target entity. This is useful when you want to find all entities
|
||||
with a relationship, regardless of the target.
|
||||
]]
|
||||
|
||||
-- Find all entities that eat something (any target)
|
||||
for entity in world:query(pair(Eats, jecs.Wildcard)) do
|
||||
local food = world:target(entity, Eats) -- Get the actual target
|
||||
print(`Entity {entity} eats {food}`)
|
||||
end
|
||||
|
||||
-- Find all entities that like someone (any target)
|
||||
for entity in world:query(pair(Likes, jecs.Wildcard)) do
|
||||
local target = world:target(entity, Likes)
|
||||
print(`Entity {entity} likes {target}`)
|
||||
end
|
||||
|
||||
--[[
|
||||
Combining relationship queries with regular components
|
||||
|
||||
You can combine relationship queries with regular component queries. This
|
||||
allows you to find entities that have both a relationship and regular
|
||||
components.
|
||||
]]
|
||||
|
||||
local Position = world:component() :: jecs.Id<vector>
|
||||
local Health = world:component() :: jecs.Id<number>
|
||||
|
||||
local player = world:entity()
|
||||
world:set(player, Position, vector.create(10, 20, 30))
|
||||
world:set(player, Health, 100)
|
||||
world:add(player, pair(ChildOf, parent))
|
||||
|
||||
-- Find all children of parent that have Position and Health
|
||||
for entity, pos, health in world:query(Position, Health, pair(ChildOf, parent)) do
|
||||
print(`Child {entity} has position {pos} and health {health}`)
|
||||
end
|
||||
|
||||
--[[
|
||||
Querying for entities with multiple relationship targets
|
||||
|
||||
An entity can have multiple relationships with the same relationship type
|
||||
but different targets. For example, bob might like both alice and charlie.
|
||||
|
||||
When querying with a wildcard, you'll get the entity once, but world:target()
|
||||
will return the first matching target. If you need all targets, you'll need
|
||||
to use a different approach (see the targets example for advanced usage).
|
||||
]]
|
||||
|
||||
local charlie = world:entity()
|
||||
world:add(bob, pair(Likes, charlie))
|
||||
|
||||
-- This query will return bob once, even though bob likes both alice and charlie
|
||||
for entity in world:query(pair(Likes, jecs.Wildcard)) do
|
||||
local target = world:target(entity, Likes)
|
||||
print(`Entity {entity} likes {target}`) -- Will show one target per entity
|
||||
end
|
||||
|
||||
--[[
|
||||
Querying for all relationships with a specific target
|
||||
|
||||
You can also query for all entities that have any relationship with a
|
||||
specific target using a wildcard for the relationship part.
|
||||
]]
|
||||
|
||||
-- Find all entities that have any relationship with alice as the target
|
||||
for entity in world:query(pair(jecs.Wildcard, alice)) do
|
||||
-- Note: This is less common and may have performance implications
|
||||
print(`Entity {entity} has some relationship with alice`)
|
||||
end
|
||||
|
||||
--[[
|
||||
Relationship pairs, just like regular component, can be associated with data.
|
||||
]]
|
||||
|
||||
local Begin = world:entity()
|
||||
local End = world:entity()
|
||||
|
||||
local e = world:entity()
|
||||
world:set(e, pair(Eats, Apples), { amount = 1 })
|
||||
|
||||
world:set(e, pair(Begin, Position), vector.create(0, 0, 0))
|
||||
world:set(e, pair(End, Position), vector.create(10, 20, 30))
|
||||
|
||||
world:add(e, pair(jecs.ChildOf, Position))
|
||||
|
||||
--[[
|
||||
Querying relationship pairs with data
|
||||
|
||||
When you query for relationship pairs that have data, you can access that
|
||||
data just like regular components.
|
||||
]]
|
||||
|
||||
-- Query for entities with Eats relationship and get the data
|
||||
for entity, eats_data in world:query(pair(Eats, Apples)) do
|
||||
print(`Entity {entity} eats apples: amount = {eats_data.amount}`)
|
||||
end
|
||||
|
||||
--[[
|
||||
When querying for relationship pairs, it is often useful to be able to find
|
||||
all instances for a given relationship or target. To accomplish this, a game
|
||||
can use wildcard expressions.
|
||||
|
||||
Wildcards may used for the relationship or target part of a pair:
|
||||
|
||||
pair(Likes, jecs.Wildcard) -- Matches all Likes relationships
|
||||
pair(jecs.Wildcard, Alice) -- Matches all relationships with Alice as target
|
||||
|
||||
Using world:target() is the recommended way to get the target in a wildcard
|
||||
query. However, if you're in a very hot path and need maximum performance,
|
||||
you can access the relationship column directly (see advanced examples).
|
||||
]]
|
||||
|
||||
for entity in world:query(pair(Eats, jecs.Wildcard)) do
|
||||
local nth = 0
|
||||
local food = world:target(entity, Eats, nth)
|
||||
while food do
|
||||
local eats_data = world:get(entity, pair(Eats, food))
|
||||
assert(eats_data) -- This coerces the type to be non-nilable for the type checker
|
||||
print(`Entity {entity} eats {food}: amount = {eats_data.amount}`)
|
||||
|
||||
nth += 1
|
||||
food = world:target(entity, Eats, nth)
|
||||
end
|
||||
end
|
||||
123
howto/100_cleanup_traits.luau
Executable file
123
howto/100_cleanup_traits.luau
Executable file
|
|
@ -0,0 +1,123 @@
|
|||
local jecs = require("@jecs")
|
||||
local pair = jecs.pair
|
||||
local world = jecs.world()
|
||||
|
||||
local T1 = world:entity()
|
||||
local T2 = world:entity()
|
||||
|
||||
--[[
|
||||
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.
|
||||
|
||||
This is what cleanup traits are for: to specify which action needs to be executed
|
||||
under which condition. They are applied to entities that have a reference to
|
||||
the entity being deleted: if I delete the Archer tag I remove the tag from all
|
||||
entities that have it.
|
||||
|
||||
To configure a cleanup policy for an entity, a (Condition, Action) pair can
|
||||
be added to it. If no policy is specified, the default cleanup action (Remove)
|
||||
is performed.
|
||||
|
||||
Cleanup Actions:
|
||||
- Remove: removes instances of the specified (component) id from all entities (default)
|
||||
- Delete: deletes all entities with specified id
|
||||
|
||||
Cleanup Conditions:
|
||||
- OnDelete: the component, tag or relationship is deleted
|
||||
- OnDeleteTarget: a target used with the relationship is deleted
|
||||
]]
|
||||
|
||||
|
||||
--[[
|
||||
(OnDelete, Remove)
|
||||
Removes the component from all entities when the component is deleted.
|
||||
Default behavior, safe cleanup.
|
||||
--]]
|
||||
|
||||
world:add(T1, pair(jecs.OnDelete, jecs.Remove))
|
||||
|
||||
local e1 = world:entity()
|
||||
world:add(e1, T1)
|
||||
|
||||
-- This will remove T1 from e
|
||||
world:delete(T1)
|
||||
print(world:has(e1, T1))
|
||||
|
||||
--[[
|
||||
When an ID added to an entity is deleted, all references to that ID are deleted
|
||||
from the storage. For example, when the component Position is deleted it is
|
||||
removed from all entities, and all archetypes with the Position component are
|
||||
deleted. While not unique to relationships, it is more common for relationships
|
||||
to trigger cleanup actions, as relationship pairs contain regular entities.
|
||||
|
||||
The opposite is also true. Because relationship pairs can contain regular entities
|
||||
which can be created on the fly, archetype creation is more common than in games
|
||||
that do not use relationships. While Jecs is optimized for fast archetypes creation,
|
||||
creating and cleaning up archetypes is inherently more expensive than creating/deleting
|
||||
an entity. Therefore archetypes creation is a factor to consider, especially for
|
||||
games that make extensive use of relationships.
|
||||
--]]
|
||||
|
||||
|
||||
--[[
|
||||
(OnDelete, Delete)
|
||||
Deletes all entities that have the component when the component is deleted.
|
||||
Cascading deletion, dangerous.
|
||||
]]
|
||||
|
||||
world:add(T2, pair(jecs.OnDelete, jecs.Remove))
|
||||
|
||||
local e2 = world:entity()
|
||||
world:add(e2, T2)
|
||||
|
||||
-- This will delete e along with T2
|
||||
world:delete(T2)
|
||||
print(`Is Entity still in the World {world:contains(e2)}`)
|
||||
print(`Is T2 still in the World {world:contains(T2)}`)
|
||||
|
||||
|
||||
--[[
|
||||
(OnDeleteTarget, Remove)
|
||||
Removes the relationship from all entities when the target is deleted.
|
||||
Safe relationship cleanup.
|
||||
]]
|
||||
|
||||
local OwnedBy = world:component()
|
||||
world:add(OwnedBy, pair(jecs.OnDeleteTarget, jecs.Remove))
|
||||
|
||||
local loot = world:entity()
|
||||
local player = world:entity()
|
||||
world:add(loot, pair(OwnedBy, player))
|
||||
|
||||
-- This will remove (OwnedBy, player) from loot
|
||||
world:delete(player)
|
||||
|
||||
print(`Is the loot still owned by the player {world:contains(loot)}`)
|
||||
|
||||
|
||||
--[[
|
||||
(OnDeleteTarget, Delete)
|
||||
Deletes all entities that have the relationship when the target is deleted.
|
||||
Hierarchical deletion (e.g., parent-child).
|
||||
]]
|
||||
|
||||
-- ChildOf actually exists as apart of jecs' builtin IDs but we demonstrate
|
||||
-- how it works here:
|
||||
local ChildOf = world:component()
|
||||
world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
|
||||
|
||||
local parent = world:entity()
|
||||
local child = world:entity()
|
||||
world:add(child, pair(ChildOf, parent))
|
||||
|
||||
-- This will delete both parent and child
|
||||
world:delete(parent)
|
||||
|
||||
print(`Is parent still in the World {world:contains(parent)}`)
|
||||
print(`Is child still in the World {world:contains(child)}`)
|
||||
40
howto/110_hooks.luau
Executable file
40
howto/110_hooks.luau
Executable file
|
|
@ -0,0 +1,40 @@
|
|||
--[[
|
||||
Component data generally need to adhere to a specific interface, and sometimes
|
||||
requires side effects to run upon certain lifetime cycles. In jecs, there are
|
||||
hooks which are component traits, that can define the behaviour of a component
|
||||
and enforce invariants, but can only be invoked through mutations on the
|
||||
component data. You can only configure a single OnAdd, OnRemove and OnChange
|
||||
hook per component, just like you can only have a single constructor and destructor.
|
||||
]]
|
||||
|
||||
local jecs = require("@jecs")
|
||||
local world = jecs.world()
|
||||
|
||||
local Transform = world:component()
|
||||
|
||||
world:set(Transform, jecs.OnAdd, function(entity, id, data)
|
||||
-- A transform component id has been added with data to entity
|
||||
print(`Transform added to entity {entity}`)
|
||||
end)
|
||||
|
||||
world:set(Transform, jecs.OnRemove, function(entity, id)
|
||||
-- A transform component id has been removed from entity
|
||||
print(`Transform removed from entity {entity}`)
|
||||
end)
|
||||
|
||||
world:set(Transform, jecs.OnChange, function(entity, id, data)
|
||||
-- A transform component id has been changed to data on entity
|
||||
print(`Transform changed on entity {entity}`)
|
||||
end)
|
||||
|
||||
--[[
|
||||
Children are cleaned up before parents
|
||||
When a parent and its children are deleted, OnRemove hooks will be invoked
|
||||
for children first, under the condition that there are no cycles in the
|
||||
relationship graph of the deleted entities. This order is maintained for any
|
||||
relationship that has the (OnDeleteTarget, Delete) trait (see Component Traits
|
||||
for more details).
|
||||
|
||||
When an entity graph contains cycles, order is undefined. This includes cycles
|
||||
that can be formed using different relationships.
|
||||
]]
|
||||
Loading…
Reference in a new issue