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

Docs addons (#112)

Browse source 
* Fix indentations

* Add addons page

* Fix indent
This commit is contained in:
Marcus 2024-08-31 04:13:47 +02:00 committed by GitHub
parent 4f65be279b
commit f91ab4049f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 1007 additions and 962 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

137
docs/.vitepress/config.mts
View file

@ -1,68 +1,69 @@
import { defineConfig } from 'vitepress' import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config // https://vitepress.dev/reference/site-config
export default defineConfig({ export default defineConfig({
title: "Jecs", title: "Jecs",
base: "/jecs/", base: "/jecs/",
description: "A VitePress Site", description: "A VitePress Site",
themeConfig: { themeConfig: {
// https://vitepress.dev/reference/default-theme-config // https://vitepress.dev/reference/default-theme-config
nav: [ nav: [
{ text: 'Learn', link: '/' }, { text: 'Learn', link: '/' },
{ text: 'API', link: '/api/jecs.md' }, { text: 'API', link: '/api/jecs.md' },
{ text: 'Examples', link: 'https://github.com/Ukendio/jecs/tree/main/examples' }, { text: 'Examples', link: 'https://github.com/Ukendio/jecs/tree/main/examples' },
], ],
sidebar: { sidebar: {
"/api/": [ "/api/": [
{ {
text: "API reference", text: "API reference",
items: [ items: [
{ text: "jecs", link: "/api/jecs" }, { text: "jecs", link: "/api/jecs" },
{ text: "World", link: "/api/world" }, { text: "World", link: "/api/world" },
{ text: "Query", link: "/api/query" } { text: "Query", link: "/api/query" }
] ]
} }
], ],
"/learn/": [ "/learn/": [
{ {
text: "Introduction", text: "Introduction",
items: [ items: [
{ text: 'Getting Started', link: '/learn/overview/get-started' }, { text: 'Getting Started', link: '/learn/overview/get-started' },
{ text: 'First Jecs Project', link: '/learn/overview/first-jecs-project' } { text: 'First Jecs Project', link: '/learn/overview/first-jecs-project' }
] ]
}, },
{ {
text: 'Concepts', text: 'Concepts',
items: [ items: [
{ text: 'Entities and Components', link: '/learn/concepts/entities-and-components' }, { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
{ text: 'Queries', link: '/learn/concepts/queries' }, { text: 'Queries', link: '/learn/concepts/queries' },
{ text: 'Relationships', link: '/learn/concepts/relationships' }, { text: 'Relationships', link: '/learn/concepts/relationships' },
{ text: 'Builtin Component Traits', link: 'learn/concepts/builtin-component-traits' } { text: 'Component Traits', link: 'learn/concepts/component-traits' },
] { text: 'Addons', link: '/learn/addons' }
}, ]
{ },
text: "FAQ", {
items: [ text: "FAQ",
{ text: 'How can I contribute?', link: '/learn/faq/contributing' } items: [
] { text: 'How can I contribute?', link: '/learn/faq/contributing' }
}, ]
},
],
"/contributing/": [ ],
{ "/contributing/": [
text: 'Contributing', {
items: [ text: 'Contributing',
{ text: 'Contribution Guidelines', link: '/learn/contributing/guidelines' }, items: [
{ text: 'Submitting Issues', link: '/learn/contributing/issues' }, { text: 'Contribution Guidelines', link: '/learn/contributing/guidelines' },
{ text: 'Submitting Pull Requests', link: '/learn/contributing/pull-requests' }, { text: 'Submitting Issues', link: '/learn/contributing/issues' },
] { text: 'Submitting Pull Requests', link: '/learn/contributing/pull-requests' },
} ]
] }
}, ]
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/ukendio/jecs' } socialLinks: [
] { icon: 'github', link: 'https://github.com/ukendio/jecs' }
} ]
}) }
})

16
docs/learn/concepts/addons.md Normal file
View file

@ -0,0 +1,16 @@
# Addons
A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request]()!
# Debuggers
## [jabby](https://github.com/alicesaidhi/jabby)
A jecs debugger with a string-based query language and entity editing capabilities.
# Schedulers
## [sapphire-jecs](https://github.com/Mark-Marks/sapphire/tree/main/crates/sapphire-jecs)
A batteries-included [sapphire](https://github.com/mark-marks/sapphire) scheduler for jecs
This page takes wording and terminology directly from Bevy's [assets page](https://bevyengine.org/assets/)

264
docs/learn/concepts/builtin-component-traits.md → docs/learn/concepts/component-traits.md
View file

@ -1,114 +1,150 @@
# Builtin Component Traits # Component Traits
Component traits are IDs and pairs that can be added to components to modify their behavior. Although it is possible to create custom traits, this manual only contains an overview of all builtin component traits supported by Jecs.
Component traits are IDs and pairs that can be added to components to modify their behavior. This manual contains an overview of all component traits supported by Jecs.
# Component
Every (component) ID comes with a `Component` which helps with the distinction between normal entities and component IDs.
# Cleanup Traits
# Tag
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. A (component) ID can be marked with `Tag´ in which the component will never contain any data. This allows for zero-cost components which improves performance for structural changes.
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. # Hooks
Hooks are part of the "interface" of a component. You could consider hooks as the counterpart to OOP methods in ECS. They define the behavior of a component, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnSet` hook per component, just like you can only have a single constructor and destructor.
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.
## Examples
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. ::: code-group
There are two cleanup actions: ```luau [luau]
local Transform= world:component()
- `Remove`: removes instances of the specified (component) id from all entities (default) world:set(Transform, OnAdd, function(entity)
- `Delete`: deletes all entities with specified id -- A transform component has been added to an entity
end)
There are two cleanup conditions: world:set(Transform, OnRemove, function(entity)
-- A transform component has been removed from the entity
- `OnDelete`: the component, tag or relationship is deleted end)
- `OnDeleteTarget`: a target used with the relationship is deleted world:set(Transform, OnSet, function(entity, value)
-- A transform component has been assigned/changed to value on the entity
## Examples end)
```
The following examples show how to use cleanup traits
```typescript [typescript]
### (OnDelete, Remove)
const Transform = world.component()
::: code-group world.set(Transform, OnAdd, (entity) => {
// A transform component has been added to an entity
```luau [luau] })
local Archer = world:component() world.set(Transform, OnRemove, (entity) => {
world:add(Archer, pair(jecs.OnDelete, jecs.Remove)) // A transform component has been removed from the entity
})
local e = world:entity() world.set(Transform, OnSet, (entity, value) => {
world:add(e, Archer) // A transform component has been assigned/changed to value on the entity
})
-- This will remove Archer from e
world:delete(Archer) ```
```
:::
```typescript [typescript]
const Archer = world.component() # Cleanup Traits
world.add(Archer, pair(jecs.OnDelete, jecs.Remove)) 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.
const e = world:entity() 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.
world.add(e, Archer)
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.
// This will remove Archer from e
world.delete(Archer) 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.
```
There are two cleanup actions:
:::
- `Remove`: removes instances of the specified (component) id from all entities (default)
### (OnDelete, Delete) - `Delete`: deletes all entities with specified id
::: code-group
There are two cleanup conditions:
```luau [luau]
local Archer = world:component() - `OnDelete`: the component, tag or relationship is deleted
world:add(Archer, pair(jecs.OnDelete, jecs.Remove)) - `OnDeleteTarget`: a target used with the relationship is deleted
local e = world:entity() ## Examples
world:add(e, Archer) The following examples show how to use cleanup traits
-- This will remove Archer from e ### (OnDelete, Remove)
world:delete(Archer) ::: code-group
```
```luau [luau]
```typescript [typescript] local Archer = world:component()
const Archer = world.component() world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
local e = world:entity()
const e = world:entity() world:add(e, Archer)
world.add(e, Archer)
-- This will remove Archer from e
// This will remove Archer from e world:delete(Archer)
world.delete(Archer) ```
```
```typescript [typescript]
::: const Archer = world.component()
world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
### (OnDeleteTarget, Delete)
const e = world:entity()
::: code-group world.add(e, Archer)
```luau [luau] // This will remove Archer from e
local ChildOf = world:component() world.delete(Archer)
world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete)) ```
local parent = world:entity() :::
local child = world:entity()
world:add(child, pair(ChildOf, parent)) ### (OnDelete, Delete)
::: code-group
-- This will delete both parent and child
world:delete(parent) ```luau [luau]
``` local Archer = world:component()
world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
```typescript [typescript]
const Archer = world.component() local e = world:entity()
world.add(Archer, pair(jecs.OnDelete, jecs.Remove)) world:add(e, Archer)
const e = world:entity() -- This will remove Archer from e
world.add(e, Archer) world:delete(Archer)
```
// This will delete e
world.delete(Archer) ```typescript [typescript]
``` const Archer = world.component()
world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
:::
const e = world:entity()
This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html) world.add(e, Archer)
// This will remove Archer from e
world.delete(Archer)
```
:::
### (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 Archer = world.component()
world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
const e = world:entity()
world.add(e, Archer)
// This will delete e
world.delete(Archer)
```
:::
This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)

1552
src/init.luau
View file

File diff suppressed because it is too large Load diff