len0rd/Concord
1
0
Fork 0
mirror of https://github.com/Keyslam-Group/Concord.git synced 2025-09-02 04:13:58 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update docs

Browse source
This commit is contained in:
Justin van der Leij 2020-03-16 10:35:55 +01:00
parent f640258852
commit b906e2a910
1 changed files with 68 additions and 134 deletions
Download patch file Download diff file Expand all files Collapse all files

202
README.md
View file

@ -19,17 +19,16 @@ Auto generated docs for Concord can be found in `docs` folder, or on the [Github
- [Entities](#entities)
- [Systems](#systems)
- [Worlds](#worlds)
- [Assemblages](#assemblages)
- [Assemblages](#assemblages)
[Quick Example](#quick-example)
[Contributors](#contributors)
[License](#licence)
---
## Installation
Download the repository and copy the 'src' folder in your project. Rename it to something that makes sense (Probably 'concord'), then require it in your project like so:
Download the repository and copy the 'concord' folder into your project. Then require it in your project like so:
```lua
local Concord = require("path.to.concord")
```
@ -42,13 +41,9 @@ local Entity = Concord.entity
local Component = Concord.component
local System = Concord.system
local World = Concord.world
local Assemblage = Concord.assemblage
-- Containers
local Components = Concord.components
local Systems = Concord.systems
local Worlds = Concord.worlds
local Assemblages = Concord.assemblages
```
---
@ -71,7 +66,7 @@ What is most important is that Components are data and nothing more. They have 0
Entities are the actual objects in your game. Like a player, an enemy, a crate, or a bullet.
Every Entity has it's own set of Components, with their own values.
A crate might have the following components:
A crate might have the following components (Note: Not actual Concord syntax):
```lua
{
position = { x = 100, y = 200 },
@ -100,7 +95,7 @@ For this they will only act on Entities that have the Components needed for this
In Concord this is done something alike this:
```lua
drawSystem = System({position, texture}) -- Define a System that takes all Entities with a position and texture Component
drawSystem = System({pool = {position, texture}}) -- Define a System that takes all Entities with a position and texture Component
function drawSystem:draw() -- Give it a draw function
for _, entity in ipairs(self.pool) do -- Iterate over all Entities that this System acts on
@ -140,40 +135,26 @@ When you define a Component or System you are actually defining a `ComponentClas
For example. If you want to get a specific Component from an Entity, you'd do `Component = Entity:get(ComponentClass)`.
When ComponentClasses or SystemClasses are required it will be written clearly in the Documentation.
#### Containers
Since you'll be defining or creating lots of Components, Systems, Worlds and Assemblages, Concord adds container tables for each of them so that they are easily accessible.
#### Requiring files
Since you'll have lots of Components and Systems in your game Concord makes it a bit easier to load things in.
These containers can be accessed through
```lua
local Components = require("path.to.concord").components
local Systems = require("path.to.concord").systems
local Worlds = require("path.to.concord").worlds
local Assemblages = require("path.to.concord").aorlds
-- Loads all files in the directory, and puts the return value in the table Systems. The key is their filename without any extension
local Systems = {}
Concord.loadNamespace("path.to.systems", Systems)
print(Systems.systemName)
-- Loads all files in the directory. Components automatically register to Concord, so loading them into a namespace isn't necessary.
Concord.loadNamespace("path.to.components")
print(Systems.componentName)
```
Concord has helper functions to fill these containers. There are the following options depending on your needs / preference:
```lua
-- Loads each file. They are put in the container according to it's filename ( 'src.components.component_1.lua' becomes 'component_1' )
Concord.loadComponents({"path.to.component_1", "path.to.component_2", "etc"})
-- Loads all files in the directory. They are put in the container according to it's filename ( 'src.components.component_1.lua' becomes 'component_1' )
Concord.loadComponents("path.to.directory.containing.components")
-- Put the ComponentClass into the container directly. Useful if you want more manual control. Note that you need to require the file in this case
Components.register("componentName", ComponentClass)
```
Things can then be accessed through their names:
```lua
local component_1_class = Components.component_1
local componentName_class = Components.componentName
```
All the above applies the same to all the other containers.
#### Method chaining
```lua
-- All functions that do something ( eg. Don't return anything ) will return self
-- Most (if not all) methods will return self
-- This allowes you to chain methods
entity
@ -182,8 +163,6 @@ entity
:remove(position)
:destroy()
--
world
:addEntity(fooEntity)
:addEntity(barEntity)
@ -192,13 +171,13 @@ world
```
### Components
When defining a ComponentClass you usually pass in a `populate` function. This will fill the Component with values.
When defining a ComponentClass you need to pass in a name and usually a `populate` function. This will fill the Component with values.
```lua
-- Create the ComponentClass with a populate function
-- Create the position class with a populate function
-- The component variable is the actual Component given to an Entity
-- The x and y variables are values we pass in when we create the Component
local positionComponentClass = Concord.component(function(component, x, y)
Concord.component("position" function(component, x, y)
component.x = x or 0
component.y = y or 0
end)
@ -206,19 +185,11 @@ end)
-- Create a ComponentClass without a populate function
-- Components of this type won't have any fields.
-- This can be useful to indiciate state.
local pushableComponentClass = Concord.component()
```
```lua
-- Manually register the ComponentClass to the container if we want
Concord.components.register("positionComponent", positionComponentClass)
-- Otherwise return the ComponentClass so it can be required
return positionComponentClass
local pushableComponentClass = Concord.component("position")
```
### Entities
Entities can be freely made and be given Components. You pass the ComponentClass and the values you want to pass. It will then create the Component for you.
Entities can be freely made and be given Components. You pass the name of the ComponentClass and the values you want to pass. It will then create the Component for you.
Entities can only have a maximum of one of each Component.
Entities can not share Components.
@ -233,43 +204,41 @@ local myEntity = Entity(myWorld) -- To add it to a world immediately ( See World
```lua
-- Give the entity the position Component defined above
-- x will become 100. y will become 50
myEntity:give(positionComponentClass, 100, 50)
myEntity:give("position", 100, 50)
```
```lua
-- Retrieve a Component
local positionComponent = myEntity[positionComponentClass]
-- or
local positionComponent = myEntity:get(positionComponentClass)
local position = myEntity.position
print(positionComponent.x, positionComponent.y) -- 100, 50
print(position.x, position.y) -- 100, 50
```
```lua
-- Remove a Component
myEntity:remove(positionComponentClass)
myEntity:remove("position")
```
```lua
-- Check if the Entity has a Component
local hasPositionComponent = myEntity:has(positionComponentClass)
print(hasPositionComponent) -- false
local hasPosition = myEntity.position and true of false
print(hasPosition) -- false
```
```lua
-- Entity:give will override a Component if the Entity already has it
-- Entity:ensure will only put the Component if the Entity does not already have it
Entity:ensure(positionComponentClass, 0, 0) -- Will give
Entity:ensure("position", 0, 0) -- Will give
-- Position is {x = 0, y = 0}
Entity:give(positionComponentClass, 50, 50) -- Will override
Entity:give("position", 50, 50) -- Will override
-- Position is {x = 50, y = 50}
Entity:give(positionComponentClass, 100, 100) -- Will override
Entity:give("position", 100, 100) -- Will override
-- Position is {x = 100, y = 100}
Entity:ensure(positionComponentClass, 0, 0) -- Wont do anything
Entity:ensure("position", 0, 0) -- Wont do anything
-- Position is {x = 100, y = 100}
```
@ -285,7 +254,7 @@ end
```lua
-- Assemble the Entity ( See Assemblages )
myEntity:assemble(myAssemblage, 100, true, "foo")
myEntity:assemble(assemblageFunction, 100, true, "foo")
```
```lua
@ -310,30 +279,21 @@ Systems can have multiple pools.
```lua
-- Create a System
local mySystemClass = Concord.system({positionComponentClass}) -- Pool will contain all Entities with a position Component
local mySystemClass = Concord.system(pool = {"position"}) -- Pool named 'pool' will contain all Entities with a position Component
-- Create a System with multiple pools
local mySystemClass = Concord.system(
{ -- This Pool's name will default to 'pool'
positionCompomponentClass,
velocityComponentClass,
pool = { -- This pool will be named 'pool'
"position",
"velocity",
},
{ -- This Pool's name will be 'secondPool'
healthComponentClass,
damageableComponentClass,
"secondPool",
secondPool = { -- This pool's name will be 'secondPool'
"health",
"damageable",
}
)
```
```lua
-- Manually register the SystemClass to the container if we want
Concord.system.register("mySystem", mySystemClass)
-- Otherwise return the SystemClass so it can be required
return mySystemClass
```
```lua
-- If a System has a :init function it will be called on creation
@ -348,16 +308,11 @@ end
function mySystemClass:update(dt)
-- Iterate over all entities in the Pool
for _, e in ipairs(self.pool)
-- Get the Entity's Components
local positionComponent = e[positionComponentClass]
local velocityComponent = e[velocityComponentClass]
-- Do something with the Components
positionComponent.x = positionComponent.x + velocityComponent.x * dt
positionComponent.y = positionComponent.y + velocityComponent.y * dt
e.position.x = e.position.x + e.velocity.x * dt
e.position.y = e.position.y + e.velocity.y * dt
end
-- Iterate over all entities in the second Pool
for _, e in ipairs(self.secondPool)
-- Do something
@ -367,24 +322,20 @@ end
```lua
-- Systems can be enabled and disabled
-- When systems are disabled their callbacks won't be executed.
-- Note that pools will still be updated
-- This is mainly useful for systems that display debug information
-- Systems are enabled by default
-- Enable a System
mySystem:enable()
-- or
mySystem:setEnable(true)
-- Disable a System
mySystem:disable()
-- or
mySystem:setEnable(false)
-- Toggle the enable state
mySystem:toggleEnabled()
-- Get enabled state
local isEnabled = mySystem:isEnabled()
print(isEnabled) -- true
print(isEnabled) -- false
```
```lua
@ -405,14 +356,6 @@ Worlds can have any number of Entities.
local myWorld = Concord.world()
```
```lua
-- Manually register the World to the container if we want
Concord.worlds.register("myWorld", myWorld)
-- Otherwise return the World so it can be required
return myWorld
```
```lua
-- Add an Entity to the World
myWorld:addEntity(myEntity)
@ -471,33 +414,31 @@ end
### Assemblages
Assemblages are helpers to 'make' Entities something.
Assemblages are functions to 'make' Entities something.
An important distinction is that they _append_ Components.
```lua
-- Make an Assemblage
-- Make an Assemblage function
-- e is the Entity being assembled.
-- cuteness and legs are variables passed in
local animalAssemblage(function(e, cuteness, legs)
function animal(e, cuteness, legs)
e
:give(cutenessComponentClass, cuteness)
:give(limbs, legs, 0) -- Variable amount of legs. 0 arm.
end)
-- Make an Assemblage that used animalAssemblage
-- Make an Assemblage that uses animal
-- cuteness is a variables passed in
local catAssemblage(function(e, cuteness)
function cat(e, cuteness)
e
:assemble(animalAssemblage, cuteness * 2, 4) -- Cats are twice as cute, and have 4 legs.
:assemble(animal, cuteness * 2, 4) -- Cats are twice as cute, and have 4 legs.
:give(soundComponent, "meow.mp3")
end)
```
```lua
-- Use an Assemblage
myEntity:assemble(catAssemblage, 100) -- 100 cuteness
-- or
catAssemblage:assemble(myEntity, 100) -- 100 cuteness
myEntity:assemble(cat, 100) -- 100 cuteness
```
---
@ -506,14 +447,13 @@ catAssemblage:assemble(myEntity, 100) -- 100 cuteness
```lua
local Concord = require("concord")
-- Defining ComponentClasses
-- I use UpperCamelCase to indicate its a class
local Position = Concord.component(function(c, x, y)
-- Defining components
Concord.component("position", function(c, x, y)
c.x = x or 0
c.y = y or 0
end)
local Velocity = Concord.component(function(c, x, y)
Concord.component("velocity", function(c, x, y)
c.x = x or 0
c.y = y or 0
end)
@ -522,27 +462,21 @@ local Drawable = Concord.component()
-- Defining Systems
local MoveSystem = Concord.system({Position, Velocity})
local MoveSystem = Concord.system(pool = {"position", "velocity"})
function MoveSystem:update(dt)
for _, e in ipairs(self.pool) do
-- I use lowerCamelCase to indicate its an instance
local position = e[Position]
local velocity = e[Velocity]
position.x = position.x + velocity.x * dt
position.y = position.y + velocity.y * dt
e.position.x = e.position.x + e.velocity.x * dt
e.position.y = e.position.y + e.velocity.y * dt
end
end
local DrawSystem = Concord.system({Position, Drawable})
local DrawSystem = Concord.system(pool = {"position", "drawable"})
function DrawSystem:draw()
for _, e in ipairs(self.pool) do
local position = e[Position]
love.graphics.circle("fill", position.x, position.y, 5)
love.graphics.circle("fill", e.position.x, e.position.y, 5)
end
end
@ -555,18 +489,18 @@ world:addSystems(MoveSystem, DrawSystem)
-- This Entity will be rendered on the screen, and move to the right at 100 pixels a second
local entity_1 = Concord.entity(world)
:give(Position, 100, 100)
:give(Velocity, 100, 0)
:give(Drawable)
:give("position", 100, 100)
:give("velocity", 100, 0)
:give("drawable")
-- This Entity will be rendered on the screen, and stay at 50, 50
local entity_2 = Concord.entity(world)
:give(Position, 50, 50)
:give(Drawable)
:give("position", 50, 50)
:give("drawable")
-- This Entity does exist in the World, but since it doesn't match any System's filters it won't do anything
local entity_3 = Concord.entity(world)
:give(Position, 200, 200)
:give("position", 200, 200)
-- Emit the events