Script PICO-EC
PICO-EC - A small scene/entity/component library built for the fantasy console, PICO-8.
Info:
- Copyright: Joeb Rogers 2018
- License: MIT
- Author: Joeb Rogers
Functions
| utilities.assign (target, source, multiple) | Assigns the contents of a table to another. |
| utilities.deepAssign (target, source, multipleSource, exclude, multipleExclude) | Deep assigns the contents of a table to another. |
| utilities.tableRemoveKey (t, k) | Removes a string key from a table. |
| utilities.changeScene (currentScene, newScene) | Unloads a scene, and loads in the specified new one. |
| _baseObject:setActive (state) | Sets an object's 'active' field. |
| _baseObject:setRemoval (state) | Sets an object's 'flagRemoval' field. |
| _entity:addComponent (component) | Add a component to the entity's list of components. |
| _entity:removeComponent (name) | Removes a component from the entity's list of components. |
| _entity:getComponent (name) | Returns a component specified by name. |
| _entity:onAddedToScene () | Called when the entity is added to a scene with the addEntity() function. |
| _entity:init () | Calls init() on all of an entity's components. |
| _entity:update () | Calls update() on all of an entity's components. |
| _entity:draw () | Calls draw() on all of an entity's components. |
| _component:onAddedToEntity () | Called when the component is added to an entity with the addComponent() function. |
| _component:init () | A function to initialise the component. |
| _component:update () | A function to update the component. |
| _component:draw () | A function to draw the component. |
| _component:setParent (parent) | Sets a reference to the component's parent entity. |
| _scene:addEntity (entity) | Adds an entity to this scene's entity list. |
| _scene:removeEntity (name) | Flags an entity for removal from the scene. |
| _scene:getEntity (name) | Returns the entity within the scene with the passed in name. |
| _scene:init () | Calls init() on all of the scene's entities. |
| _scene:update () | Calls update() on all of an scene's entities. |
| _scene:draw () | Calls draw() on all of an scene's entities. |
| _scene:onLoad () | Function called when the scene is loaded in as the active scene. |
| _scene:unload () | Function called during the change to a new scene. |
| factory.createScene (scene) | Creates and returns a new scene object. |
| factory.createEntity (entity) | Creates and returns a new entity object. |
| factory.createComponent (component) | Creates and returns a new component object. |
Tables
| utilities | A table storing various utility functions used by the ECS. |
| _baseObject | A table used as the base for a reusable GameObject. |
| _entity | A table used as a base for entities. |
| _component | A table used as a base for components. |
| _scene | A table used as a base for scenes. |
| factory | A table storing various factory functions used by the ECS. |
Fields
| ENTITY_COUNT | The number of entities currently created within the application lifetime. |
| COMPONENT_COUNT | The number of components currently created within the application lifetime. |
Functions
- utilities.assign (target, source, multiple)
-
Assigns the contents of a table to another.
Copy over the keys and values from source
tables to a target. Assign only shallow copies
to the target table. For a deep copy, use
deepAssign instead.
Parameters:
- target The table to be copied to.
- source Either a table to copy from, or an array storing multiple source tables.
- multiple Specifies whether source contains more than one table.
Returns:
-
The target table with overwritten and
appended values.
- utilities.deepAssign (target, source, multipleSource, exclude, multipleExclude)
-
Deep assigns the contents of a table to another.
Copy over the keys and values from source
tables to a target. Will recurse through child
tables to copy over their keys/values as well.
Parameters:
- target The table to be copied to.
- source Either a table to copy from, or an array storing multiple source tables.
- multipleSource Specifies whether source contains more than one table.
- exclude Either a string or an array of string containing keys to exclude from copying.
- multipleExclude Specifies whether exclude contains more than one string.
Returns:
-
The target table with overwritten and
appended values.
- utilities.tableRemoveKey (t, k)
-
Removes a string key from a table.
Parameters:
- t The table to modify.
- k The key to remove.
- utilities.changeScene (currentScene, newScene)
-
Unloads a scene, and loads in the specified new one.
Parameters:
- currentScene The currently running scene.
- newScene The new scene to load in.
Returns:
-
The newly loaded in scene.
- _baseObject:setActive (state)
-
Sets an object's 'active' field.
Parameters:
- state A bool representing what the field be set to.
- _baseObject:setRemoval (state)
-
Sets an object's 'flagRemoval' field.
Parameters:
- state A bool representing what the field be set to.
- _entity:addComponent (component)
-
Add a component to the entity's list of components.
The added component has it's parent assiged to the
entity.
Parameters:
- component The component to add.
Returns:
-
Returns early if the component
isn't valid.
- _entity:removeComponent (name)
-
Removes a component from the entity's list of components.
The specified component is flagged for removal and
will be removed once the other component's have
finished processing.
Parameters:
- name The string index of the component to remove.
- _entity:getComponent (name)
-
Returns a component specified by name.
Parameters:
- name The string index of the component to retrieve.
Returns:
-
The retrieved component.
- _entity:onAddedToScene ()
- Called when the entity is added to a scene with the addEntity() function. Has no default behaviour, should be overwritten by a custom entity.
- _entity:init ()
- Calls init() on all of an entity's components.
- _entity:update ()
-
Calls update() on all of an entity's components.
Loops back around once all components have been
updated to remove any components that have been
flagged.
Returns:
- Will return early if the entity isn't active.
- Will return before resetting indexes if no objects have been removed.
- _entity:draw ()
-
Calls draw() on all of an entity's components.
Returns:
-
Will return early if the entity isn't
active.
- _component:onAddedToEntity ()
- Called when the component is added to an entity with the addComponent() function. Has no default behaviour, should be overwritten by a custom component.
- _component:init ()
- A function to initialise the component. init is a placeholder that can be overwritten upon creation of a component. Will be called once when the application calls _init() and when a new scene's onLoad() function is called.
- _component:update ()
- A function to update the component. update is a placeholder that can be overwritten upon creation of a component. Will be called every frame when the application calls _update().
- _component:draw ()
- A function to draw the component. draw is a placeholder that can be overwritten upon creation of a component. Will be called every frame when the application calls _draw().
- _component:setParent (parent)
-
Sets a reference to the component's parent
entity.
Parameters:
- parent The entity containing this component.
- _scene:addEntity (entity)
-
Adds an entity to this scene's entity list.
Parameters:
- entity The entity to add.
Returns:
-
Will return early if the entity is
invalid.
- _scene:removeEntity (name)
-
Flags an entity for removal from the scene.
Parameters:
- name The name the entity is indexed by within the scene.
- _scene:getEntity (name)
-
Returns the entity within the scene with
the passed in name.
Parameters:
- name The name the entity is indexed by within the scene.
Returns:
-
The retrieved entity.
- _scene:init ()
- Calls init() on all of the scene's entities.
- _scene:update ()
-
Calls update() on all of an scene's entities.
Entity is skipped if not active.
Loops back around once all entities have been
updated to remove any entities that have been
flagged.
Returns:
-
Will return before resetting indexes
if no objects have been removed.
- _scene:draw ()
- Calls draw() on all of an scene's entities. Entity is skipped if not active.
- _scene:onLoad ()
- Function called when the scene is loaded in as the active scene. By default calls init() on all of it's stored entities. If planning to overwrite the onLoad() function with a custom scene, this behvaiour should be copied over to the new scene, else no entities or components will be initialised unless the scene is the loaded in the application _init().
- _scene:unload ()
- Function called during the change to a new scene. To be overwritten if any custom behaviours need special attention before being removed.
- factory.createScene (scene)
-
Creates and returns a new scene object.
Will either return a new default scene or
one combined with a passed in custom scene.
Parameters:
- scene A custom scene to combine with the default scene.
Returns:
-
The created scene object.
- factory.createEntity (entity)
-
Creates and returns a new entity object.
Will either return a new default entity or
one combined with a passed in custom entity.
Also increments the global entity count.
Parameters:
- entity A custom entity to combine with the default entity.
Returns:
-
The created entity object.
- factory.createComponent (component)
-
Creates and returns a new component object.
Will either return a new default component or
one combined with a passed in custom component.
Also increments the global component count.
Parameters:
- component A custom component to combine with the default component.
Returns:
-
The created component object.
Tables
- utilities
- A table storing various utility functions used by the ECS.
- _baseObject
-
A table used as the base for a
reusable GameObject.
Fields:
- active Whether the current object should be processed. If disabled, this object won't be updated or drawn.
- flagRemoval Whether the current object should be flagged for removal. If set to true, the object will be cleaned up once it's parent has finished processing.
- _entity
-
A table used as a base for entities.
This table is also assigned the
properties of _baseObject.
This table can be combined with a
custom entity object with overwritten
fields and functions when the
createEntity() function is called.
Fields:
- _components A table containing the entity's added components.
- _componentsIndexed A table containing the entity's added components, indexed in the order they were added to the entity.
- type A string containing the object's "type".
- name A string containing the entity's name. Used for indexing within the scene.
- ind The index of this entity's position within the scene's ordererd array.
- _component
-
A table used as a base for components.
This table is also assigned the
properties of _baseObject.
This table can be combined with a
custom component object with overwritten
fields and functions when the
createComponent() function is called.
This is the intended method for creating
custom behaviours.
Fields:
- parent A reference to the entity that contains this component.
- type A string containing the object's "type".
- name A string containing the component's name. Used for indexing within the parent entity.
- ind The index of this component's position within the entity's ordererd array.
- _scene
-
A table used as a base for scenes.
This table can be combined with a
custom scene object with overwritten
fields and functions when the
createScene() function is called.
Fields:
- _entities A list of all the entities currently added to this scene.
- _entitiesIndexed A table containing the scenes's added entities, indexed in the order they were added to the scene.
- type A string containing the object's "type".
- factory
- A table storing various factory functions used by the ECS.