diff --git a/asset/asset.lua b/asset/asset.lua index 570618c..91e3be0 100644 --- a/asset/asset.lua +++ b/asset/asset.lua @@ -1,21 +1,44 @@ ---- ubiquitousse.asset --- No dependencies. - ---- Asset manager. Loads asset and cache them. --- This file has no dependency to either ubiquitousse or a ubiquitousse backend. +--- Asset manager. +-- +-- Loads asset and cache them. +-- -- This only provides a streamlined way to handle asset, and doesn't handle the actual file loading/object creation itself; you are expected to provide your own asset loaders. --- See the __call method for more details on how assets are loaded. Hopefully this will allow you to use asset which are more game-specific than "image" or "audio". +-- +-- See the `Asset:__call` method for more details on how assets are loaded. Hopefully this will allow you to use asset which are more game-specific than "image" or "audio". +-- +-- No dependencies. +-- @module asset + +--- Asset manager. +-- @type Asset local asset_mt = { + --- A prefix for asset names. + -- @ftype string + prefix = nil, + + --- The asset cache. Each cached asset is indexed with a string key "type.assetName". + -- @ftype table {["assetName"]=asset} + cache = nil, + + --- The loaders table. + -- @ftype table {["prefix"]=function, ...} + loaders = nil, + --- Load (and cache) an asset. + -- -- Asset name are similar to Lua module names (directory separator is the dot . and no extention should be specified). -- To load an asset, ubiquitousse will try every loaders in the loader list with a name that prefix the asset name. -- The first value returned will be used as the asset value. + -- -- Loaders are called with the arguments: + -- -- * path: the asset full path, except extension -- * ...: other arguments given after the asset name. Can only be number and strings. - -- @tparam assetName string the asset's full name - -- @tparam ... number/string other arguments for the asset loader + -- @tparam string assetName string the asset's full name + -- @tparam number/string ... other arguments for the asset loader -- @return the asset + -- @usage + -- local image = asset("image.example") __call = function(self, assetName, ...) local cache = self.cache local hash = table.concat({assetName, ...}, ".") @@ -36,6 +59,7 @@ local asset_mt = { end, --- Preload a list of assets. + -- @tparam {"asset1",...} list list of assets to load load = function(self, list) for _, asset in ipairs(list) do self(asset) @@ -50,27 +74,28 @@ local asset_mt = { } asset_mt.__index = asset_mt +--- Asset module. +-- @section end + local asset = { --- Create a new asset manager. + -- -- If the caching "mode" is set to auto (default), the asset manager will allow assets to be automaticaly garbage collected by Lua. + -- -- If set to "manual", the assets will not be garbage collected unless the clear method is called. -- "manual" mode is useful if you have assets that are particularly slow to load and you want full control on when they are loaded and unloaded (typically a loading screen). - -- @tparam directory string the directory in which the assets will be loaded - -- @tparam loaders table loaders table: {prefix = function, ...} - -- @tparam mode string[opt="auto"] caching mode - new = function(dir, loaders, mode) + -- @tparam string directory the directory in which the assets will be loaded + -- @tparam table loaders loaders table: {prefix = function, ...} + -- @tparam[opt="auto"] string mode caching mode + -- @treturn Asset the new asset manager + new = function(directory, loaders, mode) local cache = {} if mode == nil or mode == "auto" then setmetatable(cache, { __mode = "v" }) end return setmetatable({ - --- A prefix for asset names - prefix = dir..".", - - --- The asset cache. Each cached asset is indexed with a string key "type.assetName". + prefix = directory..".", cache = cache, - - --- The loaders table. loaders = loaders }, asset_mt) end diff --git a/config.ld b/config.ld index 0027624..5e78f7b 100644 --- a/config.ld +++ b/config.ld @@ -8,11 +8,26 @@ See [main module](modules/init.html) for more information, or the [GitHub page]( --package = "ubiquitousse" format = "discount" -style = "!fixed" -no_summary = true +style = "!new" not_luadoc = true -custom_tags = { { "require", title="Requires" } } +custom_tags = { + { "require", title="Requires" }, + { "ftype", title="Type", format = function(x) + local firstWord, rest = x:match("^([^%s]*)(.*)$") + return ('%s%s'):format(firstWord, rest) + end }, + { "ro", hidden=true }, + { "callback", hidden=true }, +} +custom_display_name_handler = function(item, default_handler) + if item.tags.callback then + return default_handler(item) .. ' [callback]' + elseif item.tags.ro then + return default_handler(item) .. ' [read-only]' + end + return default_handler(item) +end topics = { "README.md", "LICENSE" } -file = { "init.lua", "ldtk/ldtk.can" } +file = { "init.lua", "ldtk/ldtk.can", "ecs/ecs.can", "asset/asset.lua" } diff --git a/doc/index.html b/doc/index.html index caff3ee..4b7a5ad 100644 --- a/doc/index.html +++ b/doc/index.html @@ -4,7 +4,7 @@ Ubiquitousse reference - + @@ -32,8 +32,10 @@

Modules

Topics

+ + + + +

Parameters:

+ + +

Returns:

+
    + + Asset + the new asset manager +
+ + + + + + +

Asset objects

+ +
+ Asset manager. +
+
+
+ + Asset.prefix +
+
+ A prefix for asset names. + + +

Type:

+ + + + + + + + + +
+
+ + Asset.cache +
+
+ The asset cache. Each cached asset is indexed with a string key “type.assetName”. + + +

Type:

+ + + + + + + + + +
+
+ + Asset.loaders +
+
+ The loaders table. + + +

Type:

+ + + + + + + + + +
+
+ + Asset:__call (assetName, ...) +
+
+

Load (and cache) an asset.

+ +

Asset name are similar to Lua module names (directory separator is the dot . and no extention should be specified). + To load an asset, ubiquitousse will try every loaders in the loader list with a name that prefix the asset name. + The first value returned will be used as the asset value.

+ +

Loaders are called with the arguments:

+ + + + + + + + + + +

Parameters:

+ + +

Returns:

+
    + + the asset +
+ + + +

Usage:

+ + +
+
+ + Asset:load (list) +
+
+ Preload a list of assets. + + + + + + +

Parameters:

+ + + + + + +
+
+ + Asset:clear () +
+
+ Allow loaded assets to be garbage collected. + Only useful if the caching mode is set to “manual” duritng creation. + + + + + + + + + + + +
+
+ + + + +
+generated by LDoc 1.4.6 +Last updated 2021-12-25 17:06:47 +
+ + + diff --git a/doc/modules/ecs.html b/doc/modules/ecs.html new file mode 100644 index 0000000..3bfeb5f --- /dev/null +++ b/doc/modules/ecs.html @@ -0,0 +1,1368 @@ + + + + + Ubiquitousse reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module ecs

+

ECS (entity compenent system) library

+ +

Entity Component System library, inspired by the excellent tiny-ecs.

+

Main differences include:

+ +
    +
  • ability to nest systems;
    • +
  • instanciation of systems for each world (no shared state);
    • +
  • adding and removing entities is done instantaneously
    • +
  • ability to add and remove components from entities after they were added to the world.
    • +
+ + +

No mandatory dependency. + Optional dependency: ubiquitousse.scene, to allow quick creation of ECS-based scenes.

+ +

The module returns a table that contains several functions, world or scene are starting points + to create your world.

+

Usage:

+
    + 
    TODO
+
    +
+ + +

Functions

+ + + + + + + + + + + + + + + + + +
world (...)Create and returns a world system based on a list of systems.
all (...)Returns a filter that returns true if, for every argument, a field with the same name exists in the entity.
any (...)Returns a filter that returns true if one of the arguments if the name of a field in the entity.
scene (name[, systems={}[, entities={}]])If uqt.scene is available, returns a new scene that will consist of a ECS world with the specified systems and entities.
+

Entity table

+ +
+

Entity system table.

+ + + + + +
entity +
+

System objects

+ +
+

Modifiable fields

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
System.nameName of the system.
System.systemsList of subsystems.
System.intervalIf not false, the system will only update every interval seconds.
System.activeThe system and its susbsystems will only update if this is true.
System.visibleThe system and its subsystems will only draw if this is true.
System.defaultDefaults value to put into the entities’s system table when they are added.
System.methodsDefaults methods to assign to the entities’s system table when they are added.
+

Callbacks.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
System:filter (e) [callback]Called when checking if an entity should be added to this system.
System:compare (e1, e2) [callback]Called when adding an entity to this system determining its order.
System:onAdd (s) [callback]Called when adding an entity to the system.
System:onRemove (s) [callback]Called when removing an entity from the system.
System:onInstance () [callback]Called when the system is instancied, before any call to System:onAddToWorld (including other systems in the world).
System:onAddToWorld (world) [callback]Called when the system is added to a world.
System:onRemoveFromWorld (world) [callback]Called when the system is removed from a world (i.e., the world is destroyed).
System:onDestroy () [callback]Called when the world is destroyed, after every call to System:onRemoveFromWorld (including other systems in the world).
System:onUpdate (dt) [callback]Called when updating the system.
System:onDraw () [callback]Called when drawing the system.
System:process (s, dt) [callback]Called when updating the system, for every entity the system contains.
System:render (s) [callback]Called when drawing the system, for every entity the system contains.
+

Read-only fields

+ + + + + + + + + + + + + +
System.world [read-only]The world the system belongs to.
System.entityCount [read-only]Number of entities in the system.
System.s [read-only]Map of all named systems in the world (not only subsystems).
+

Methods.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
System:add (e, ...)Add entities to the system and its subsystems.
System:refresh (e, ...)Refresh an entity’s systems.
System:remove (e, ...)Remove entities to the system and its subsystems.
System:has (e, ...)Returns true if every entity is in the system.
System:iter ()Returns an iterator that iterate through the entties in this system.
System:clear ()Remove every entity from the system and its subsystems.
System:update (dt)Try to update the system and its subsystems.
System:draw ()Try to draw the system and its subsystems.
System:destroy ()Remove all the entities and subsystems in this system.
+ +
+
+ + +

Functions

+ +
+
+ + world (...) +
+
+ Create and returns a world system based on a list of systems. + The systems will be instancied for this world. + + + + + + +

Parameters:

+
    +
  • ... + table,... + list of (uninstancied) system tables +
    • +
+ +

Returns:

+
    + + System + the world system +
+ + + + +
+
+ + all (...) +
+
+ Returns a filter that returns true if, for every argument, a field with the same name exists in the entity. + + + + + + +

Parameters:

+
    +
  • ... + string,... + list of field names that must be in entity +
    • +
+ +

Returns:

+
    + + function(e) + that returns true if e has all the fields +
+ + + + +
+
+ + any (...) +
+
+ Returns a filter that returns true if one of the arguments if the name of a field in the entity. + + + + + + +

Parameters:

+
    +
  • ... + string,... + list of field names that may be in entity +
    • +
+ +

Returns:

+
    + + function(e) + that returns true if e has at leats one of the fields +
+ + + + +
+
+ + scene (name[, systems={}[, entities={}]]) +
+
+ If uqt.scene is available, returns a new scene that will consist of a ECS world with the specified systems and entities. + +

Requires:

+
    + ubiquitousse.scene +
+ + + + +

Parameters:

+
    +
  • name + string + the name of the new scene +
    • +
  • systems + table + list of systems to add to the world + (default {}) +
    • +
  • entities + table + list of entities to add to the world + (default {}) +
    • +
+ +

Returns:

+
    + + scene + the new scene +
+ + + + +
+
+

Entity table

+ +
+ TODO +
+
+
+

Entity system table.

+
+ + +
+
+ + + + + + + + + + + + +
+ + entity +
+
+ + + + + + + + + + + + + +
+
+

System objects

+ +
+ System fields and methods.

+ +

When they are added to a world, a new, per-world self table is created and used for every method call (which we call “instancied system”). + Instancied systems can be retrieved in system.s or system.systems.

+ +

The “world” is just the top-level system, behaving in exactly the same way as other systems.

+ +

Every field defined below is optional and can be accessed or redefined at any time, unless written otherwise. Though you would typically set them + when creating your system. +

+
+
+

Modifiable fields

+
+ + +
+
+ + + + + + + + + + + + +
+ + System.name +
+
+ Name of the system. + Used to create a field with the system’s name in world.s and into each entity (the “entity’s system table”) that’s in this system. + If not set, the entity will not have a system table.

+ +

Do not change after system instanciation. + + +

Type:

+
    +
  • string
    • +
  • nil if no name
    • +
+ + + + + + + + +
+
+ + System.systems +
+
+ List of subsystems. + On a instancied system, this is a list of the same subsystems, but instancied for this world.

+ +

Do not change after system instanciation. + + +

Type:

+
    +
  • table
    • +
  • nil if no subsystem
    • +
+ + + + + + + + +
+
+ + System.interval +
+
+ If not false, the system will only update every interval seconds. + false by default. + + +

Type:

+
    +
  • number interval of time between each update
    • +
  • false to disable
    • +
+ + + + + + + + +
+
+ + System.active +
+
+ The system and its susbsystems will only update if this is true. + true by default. + + +

Type:

+
    + boolean +
+ + + + + + + + +
+
+ + System.visible +
+
+ The system and its subsystems will only draw if this is true. + true by default. + + +

Type:

+
    + boolean +
+ + + + + + + + +
+
+ + System.default +
+
+ Defaults value to put into the entities’s system table when they are added. Will recursively fill missing values.

+ +

When an entity is added to a system, a .entity field is always set in the system table, referring to the full entity table.

+ +

Changing this will not affect entities already in the system. + + +

Type:

+
    +
  • table
    • +
  • nil if no default
    • +
+ + + + + + + + +
+
+ + System.methods +
+
+ Defaults methods to assign to the entities’s system table when they are added.

+ +

When calling the methods with entity.systemName:method(…), the method will actually receive the + arguments method(system, system table, …). Methamethods are accepted. New methods can be + created anytime. + + +

Type:

+
    +
  • table
    • +
  • nil if no methods
    • +
+ + + + + + + + +
+
+

Callbacks.

+
+ Functions that are called when something happens in the system. + Redefine them to change system behaviour. +
+
+ + + + + + + + + + + + +
+ + System:filter (e) [callback] +
+
+ Called when checking if an entity should be added to this system. + Returns true if the entity should be added to this system (and therefore its subsystems).

+ +

If this is a string or a table, it will be converted to a filter function on instanciation using ecs.any.

+ +

If this true, will accept every entity; if false, reject every entity.

+ +

Will only test entities when they are added; changing this after system creation will not affect entities already in the system.

+ +

By default, rejects everything. + + + + + + +

Parameters:

+
    +
  • e + table + entity table to check +
    • +
+ +

Returns:

+
    + + boolean + true if entity should be added +
+ + + + +
+
+ + System:compare (e1, e2) [callback] +
+
+ Called when adding an entity to this system determining its order. + Returns true if e1 <= e2. e1 and e2 are two entities.

+ +

Used to place the entity in the sorted entity list when it is added; changing this after system creation + will not change the order of entities already in the system.

+ +

By default, entities are in the same order they were inserted. + + + + + + +

Parameters:

+
    +
  • e1 + table + entity table to check for inferiority +
    • +
  • e2 + table + entity table to check for superiority +
    • +
+ +

Returns:

+
    + + boolean + true if e1 <= e2 +
+ + + + +
+
+ + System:onAdd (s) [callback] +
+
+ Called when adding an entity to the system. + + + + + + +

Parameters:

+
    +
  • s + table + the entity’s system table +
    • +
+ + + + + +
+
+ + System:onRemove (s) [callback] +
+
+ Called when removing an entity from the system. + + + + + + +

Parameters:

+
    +
  • s + table + the entity’s system table +
    • +
+ + + + + +
+
+ + System:onInstance () [callback] +
+
+ Called when the system is instancied, before any call to System:onAddToWorld (including other systems in the world). + + + + + + + + + + + +
+
+ + System:onAddToWorld (world) [callback] +
+
+ Called when the system is added to a world. + + + + + + +

Parameters:

+
    +
  • world + System + world system +
    • +
+ + + + + +
+
+ + System:onRemoveFromWorld (world) [callback] +
+
+ Called when the system is removed from a world (i.e., the world is destroyed). + + + + + + +

Parameters:

+
    +
  • world + System + world system +
    • +
+ + + + + +
+
+ + System:onDestroy () [callback] +
+
+ Called when the world is destroyed, after every call to System:onRemoveFromWorld (including other systems in the world). + + + + + + + + + + + +
+
+ + System:onUpdate (dt) [callback] +
+
+ Called when updating the system. + + + + + + +

Parameters:

+
    +
  • dt + number + delta-time since last update +
    • +
+ + + + + +
+
+ + System:onDraw () [callback] +
+
+ Called when drawing the system. + + + + + + + + + + + +
+
+ + System:process (s, dt) [callback] +
+
+ Called when updating the system, for every entity the system contains. Called after System:onUpdate was called on the system. + + + + + + +

Parameters:

+
    +
  • s + table + the entity’s system table +
    • +
  • dt + number + delta-time since last update +
    • +
+ + + + + +
+
+ + System:render (s) [callback] +
+
+ Called when drawing the system, for every entity the system contains. Called after System:onDraw was called on the system. + + + + + + +

Parameters:

+
    +
  • s + table + the entity’s system table +
    • +
+ + + + + +
+
+

Read-only fields

+
+ + +
+
+ + + + + + + + + + + + +
+ + System.world [read-only] +
+
+ The world the system belongs to. + + +

Type:

+
    + System world +
+ + + + + + + + +
+
+ + System.entityCount [read-only] +
+
+ Number of entities in the system. + + +

Type:

+
    + integer +
+ + + + + + + + +
+
+ + System.s [read-only] +
+
+ Map of all named systems in the world (not only subsystems). Same for every system from the same world. + + +

Type:

+
    + table {[system.name]=instanciedSystem, ...} +
+ + + + + + + + +
+
+

Methods.

+
+ Methods available on instancied system table. +
+
+ + + + + + + + + + + + +
+ + System:add (e, ...) +
+
+ Add entities to the system and its subsystems.

+ +

Will skip entities that are already in the system.

+ +

Entities are added to subsystems after they were succesfully added to their parent system.

+ +

If this is called on a subsystem instead of the world, be warned that this will bypass all the parent’s systems filters.

+ +

Since System:remove will not search for entities in systems where they should have been filtered out, the added entities will not be removed + when calling :remove on a parent system or the world. The entity can be removed by calling System:remove on the system System:add was called on.

+ +

Complexity: O(1) per unordered system, O(entityCount) per ordered system. + + + + + + +

Parameters:

+
    +
  • e + table + entity to add +
    • +
  • ... + table... + other entities to add +
    • +
+ +

Returns:

+
    + + e,... + the function arguments +
+ + + + +
+
+ + System:refresh (e, ...) +
+
+ Refresh an entity’s systems.

+ +

Behave similarly to System:add, but if the entity is already in the system, instead of skipping it, it + will check for new and removed components and add and remove from (sub)systems accordingly.

+ +

Complexity: O(1) per system + add/remove complexity. + + + + + + +

Parameters:

+
    +
  • e + table + entity to refresh +
    • +
  • ... + table... + other entities to refresh +
    • +
+ +

Returns:

+
    + + e,... + the function arguments +
+ + + + +
+
+ + System:remove (e, ...) +
+
+ Remove entities to the system and its subsystems.

+ +

Will skip entities that are not in the system.

+ +

Entities are removed from subsystems before they are removed from their parent system.

+ +

If you intend to call this on a subsystem instead of the world, please read the warning in System:add.

+ +

Returns all removed entities.

+ +

Complexity: O(1) per system. + + + + + + +

Parameters:

+
    +
  • e + table + entity to remove +
    • +
  • ... + table... + other entities to remove +
    • +
+ +

Returns:

+
    + + e,... + the function arguments +
+ + + + +
+
+ + System:has (e, ...) +
+
+ Returns true if every entity is in the system.

+ +

Complexity: O(1). + + + + + + +

Parameters:

+
    +
  • e + table + entity that may be in the system +
    • +
  • ... + table... + other entities that may be in the system +
    • +
+ +

Returns:

+
    + + boolean + true if every entity is in the system +
+ + + + +
+
+ + System:iter () +
+
+ Returns an iterator that iterate through the entties in this system. + + + + + + + +

Returns:

+
    + + iterator + iterator over the entities in this system, in order +
+ + + + +
+
+ + System:clear () +
+
+ Remove every entity from the system and its subsystems. + + + + + + + + + + + +
+
+ + System:update (dt) +
+
+ Try to update the system and its subsystems. Should be called on every game update.

+ +

Subsystems are updated after their parent system. + + + + + + +

Parameters:

+
    +
  • dt + number + delta-time since last update +
    • +
+ + + + + +
+
+ + System:draw () +
+
+ Try to draw the system and its subsystems. Should be called on every game draw.

+ +

Subsystems are drawn after their parent system. + + + + + + + + + + + +

+
+ + System:destroy () +
+
+ Remove all the entities and subsystems in this system. + + + + + + + + + + + +
+
+ + +
+
+
+generated by LDoc 1.4.6 +Last updated 2021-12-25 17:06:47 +
+
+ + diff --git a/doc/modules/ldtk.html b/doc/modules/ldtk.html index 4e29600..b94ab3f 100644 --- a/doc/modules/ldtk.html +++ b/doc/modules/ldtk.html @@ -4,7 +4,7 @@ Ubiquitousse reference - + @@ -31,96 +31,25 @@
  • Index
    • +

    Contents

    + -

    Tileset

    - -

    Layer

    - -

    Tile

    - -

    IntTile

    - -

    Entity

    - -

    Level

    - -

    Project

    - -

    Module

    -

    Modules

    Topics

    + + + + +

    Parameters:

    + + +

    Returns:

    +
      + + Project + the loaded LDtk project +
    + + + + + + +

    Tileset objects

    Tileset object. @@ -180,6 +414,9 @@ end The tileset LÖVE image object. + + + @@ -188,12 +425,12 @@ end -

    Layer

    +

    Layer objects

    Layer object.

    -

    Part of a Level. +

    Part of a Level.

    @@ -208,6 +445,9 @@ end
      love
    + + + @@ -220,9 +460,12 @@ end Layer.level
    - Level this layer belongs to. + Level this layer belongs to. + + + @@ -238,6 +481,9 @@ end The layer name. + + + @@ -253,6 +499,9 @@ end Type of layer: IntGrid, Entities, Tiles or AutoLayer (string). + + + @@ -268,6 +517,9 @@ end Whether the layer is visible or not. + + + @@ -283,6 +535,9 @@ end The layer opacity (0-1). + + + @@ -298,6 +553,9 @@ end The layer order: smaller order means it is on top. + + + @@ -313,6 +571,9 @@ end X position of the layer relative to the level. + + + @@ -328,6 +589,9 @@ end Y position of the layer relative to the level. + + + @@ -343,6 +607,9 @@ end Size of the grid on this layer. + + + @@ -358,6 +625,9 @@ end Width of the layer, in grid units. + + + @@ -373,6 +643,9 @@ end Height of the layer, in grid units. + + + @@ -385,9 +658,12 @@ end Layer.entities
    - (Entities layer only) List of Entity in the layer. + (Entities layer only) List of Entity in the layer. + + + @@ -400,9 +676,12 @@ end Layer.tiles
    - (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) List of Tiles in the layer. + (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) List of Tiles in the layer. + + + @@ -415,9 +694,12 @@ end Layer.tileset
    - (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) Tileset object associated with the layer. + (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) Tileset object associated with the layer. + + + @@ -433,6 +715,9 @@ end (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) LÖVE SpriteBatch containing the layer. + + + @@ -445,9 +730,12 @@ end Layer.intTiles
    - (IntGrid without AutoLayer rules layer only) list of IntTiles in the layer. + (IntGrid without AutoLayer rules layer only) list of IntTiles in the layer. + + + @@ -456,7 +744,7 @@ end
    -

    Tile

    +

    Tile objects

    Tile object.

    @@ -474,6 +762,9 @@ end Layer the tile belongs to. + + + @@ -489,6 +780,9 @@ end X position of the tile relative to the layer. + + + @@ -504,6 +798,9 @@ end Y position of the tile relative to the layer. + + + @@ -519,6 +816,9 @@ end Whether the tile is flipped horizontally. + + + @@ -534,6 +834,9 @@ end Whether the tile is flipped vertically. + + + @@ -549,6 +852,9 @@ end Tags associated with the tile: can be used either as a list of tags or a map of activated tags tags[name] == true. + + + @@ -564,6 +870,9 @@ end Custom data associated with the tile, if any. + + + @@ -579,6 +888,9 @@ end Quad associated with the tile (relative to the layer’s tileset). + + + @@ -587,7 +899,7 @@ end -

    IntTile

    +

    IntTile objects

    IntTile object.

    @@ -605,6 +917,9 @@ end Layer the IntTile belongs to. + + + @@ -620,6 +935,9 @@ end X position of the IntTile relative to the layer. + + + @@ -635,6 +953,9 @@ end Y position of the IntTile relative to the layer. + + + @@ -650,6 +971,9 @@ end Name of the IntTile. + + + @@ -665,6 +989,9 @@ end Integer value of the IntTile. + + + @@ -680,6 +1007,9 @@ end Color of the IntTile. + + + @@ -688,7 +1018,7 @@ end -

    Entity

    +

    Entity objects

    Entity object.

    @@ -703,9 +1033,12 @@ end Entity.layer
    - Layer this entity belongs to. + Layer this entity belongs to. + + + @@ -721,6 +1054,9 @@ end The entity name. + + + @@ -736,6 +1072,9 @@ end X position of the entity relative to the layer. + + + @@ -751,6 +1090,9 @@ end Y position of the entity relative to the layer. + + + @@ -766,6 +1108,9 @@ end The entity width. + + + @@ -781,6 +1126,9 @@ end The entity height. + + + @@ -796,6 +1144,9 @@ end Scale factor on x axis relative to original entity size. + + + @@ -811,6 +1162,9 @@ end Scale factor on y axis relative to original entity size. + + + @@ -826,6 +1180,9 @@ end The entity pivot point x position relative to the entity. + + + @@ -841,6 +1198,9 @@ end The entity pivot point x position relative to the entity. + + + @@ -856,6 +1216,9 @@ end Entity color. + + + @@ -871,6 +1234,9 @@ end Entity tile, if any. Is a table { tileset = associated tileset object, quad = associated quad }. + + + @@ -886,6 +1252,9 @@ end Map of custom fields of the entity. + + + @@ -906,6 +1275,9 @@ end
      love
    + + + @@ -914,14 +1286,14 @@ end
    -

    Level

    +

    Level objects

    Level object.

    Levels are not automatically loaded in order to not waste ressources if your project is large; so before drawing or operating on a level, you will need to call its Level:load method.

    -

    Part of a Project. +

    Part of a Project.

    @@ -938,6 +1310,9 @@ end
      love
    + + + @@ -947,7 +1322,7 @@ end
    - Level:load ([callbacks]) + Level:load ([, callbacks])
    Load the level. @@ -956,10 +1331,10 @@ end

    You can optionally specify some callbacks for the loading process:

      -
    • onAddLayer(layer) will be called for every new layer loaded, with the Layer as sole argument
      • -
    • onAddTile(tile) will be called for every new tile loaded, with the Tile as sole argument
      • -
    • onAddIntTile(tile) will be called for every new IntGrid tile loaded, with the IntTile as sole argument
      • -
    • onAddEntity(entity) will be called for every new entity loaded, with the Entity as sole argument
      • +
    • onAddLayer(layer) will be called for every new layer loaded, with the Layer as sole argument
      • +
    • onAddTile(tile) will be called for every new tile loaded, with the Tile as sole argument
      • +
    • onAddIntTile(tile) will be called for every new IntGrid tile loaded, with the IntTile as sole argument
      • +
    • onAddEntity(entity) will be called for every new entity loaded, with the Entity as sole argument
    @@ -970,15 +1345,18 @@ end
      love
    + + +

    Parameters:

      -
    • callbacks - tab +
    • callbacks + table - (optional) -
      • + (optional) +
    @@ -988,7 +1366,7 @@ end
    - Level:unload ([callbacks]) + Level:unload ([, callbacks])

    Unload the level. @@ -997,24 +1375,27 @@ end

    You can optionally specify some callbacks for the unloading process:

      -
    • onAddLayer(layer) will be called for every new layer unloaded, with the Layer as sole argument
      • -
    • onAddTile(tile) will be called for every new tile unloaded, with the Tile as sole argument
      • -
    • onAddIntTile(tile) will be called for every new IntGrid tile unloaded, with the IntTile as sole argument
      • -
    • onAddEntity(entity) will be called for every new entity unloaded, with the Entity as sole argument
      • +
    • onAddLayer(layer) will be called for every new layer unloaded, with the Layer as sole argument
      • +
    • onAddTile(tile) will be called for every new tile unloaded, with the Tile as sole argument
      • +
    • onAddIntTile(tile) will be called for every new IntGrid tile unloaded, with the IntTile as sole argument
      • +
    • onAddEntity(entity) will be called for every new entity unloaded, with the Entity as sole argument
    + + +

    Parameters:

      -
    • callbacks - tab +
    • callbacks + table - (optional) -
      • + (optional) +
    @@ -1027,9 +1408,12 @@ end Level.project
    - Project this level belongs to. + Project this level belongs to. + + + @@ -1045,6 +1429,9 @@ end Whether this level is currently loaded or not (boolean). + + + @@ -1060,6 +1447,9 @@ end The level name (string). + + + @@ -1075,6 +1465,9 @@ end The level x position (number). + + + @@ -1090,6 +1483,9 @@ end The level y position (number). + + + @@ -1105,6 +1501,9 @@ end The level width (number). + + + @@ -1120,6 +1519,9 @@ end The level height (number). + + + @@ -1135,6 +1537,9 @@ end Map of custom fields of the level (table). + + + @@ -1147,9 +1552,12 @@ end Level.layers
    - List of Layers in the level (table). + List of Layers in the level (table). + + + @@ -1158,7 +1566,7 @@ end
    -

    Project

    +

    Project objects

    Project object.

    @@ -1171,50 +1579,18 @@ end Project.levels
    - List of Levels in this project. + List of Levels in this project. + + + -
    - -

    Module

    - -
    - ubiquitousse.ldtk returns a single function, LDtk. -
    -
    -
    - - LDtk (path) -
    -
    - Load a LDtk project. - - - -

    Parameters:

    -
      -
    • path - string - to LDtk project file (.ldtk) -
      • -
    - -

    Returns:

    -
      - - Project - the loaded LDtk project -
    - - - -
    @@ -1223,7 +1599,7 @@ end
    generated by LDoc 1.4.6 -Last updated 2021-12-24 23:49:41 +Last updated 2021-12-25 17:06:47
    diff --git a/doc/modules/init.html b/doc/modules/ubiquitousse.html similarity index 71% rename from doc/modules/init.html rename to doc/modules/ubiquitousse.html index cf423ba..37d27fb 100644 --- a/doc/modules/init.html +++ b/doc/modules/ubiquitousse.html @@ -4,7 +4,7 @@ Ubiquitousse reference - + @@ -31,24 +31,18 @@
  • Index
    • - - -

    Fields

    -
      -
    • version
      • -
    • asset
      • -
    • ecs
      • -
    • input
      • -
    • ldtk
      • -
    • scene
      • -
    • signal
      • -
    • timer
      • -
    • util
      • +

      Contents

      + + +

      Modules

      Topics

        @@ -60,7 +54,7 @@
        -

        Module init

        +

        Module ubiquitousse

        Ubiquitousse main module.

        Set of various Lua libraries to make game development easier, mainly made to be used alongside the LÖVE game framework. Nothing that hasn’t been done before, but these are tailored to what I need. They can be used independently too, and are relatively portable, even without LÖVE.

        @@ -118,6 +112,49 @@
      +

      Fields

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      versionUbiquitousse version string (currently "0.1.0").
      assetAsset manager module, if available.
      ecsEntity Component System, if available.
      inputInput management, if available.
      ldtkLDtk level import, if available.
      sceneScene management, if available.
      signalSignal management, if available.
      timerTimer utilities, if available.
      utilVarious useful functions, if available.
      + +
      +
      +

      Fields

      @@ -130,6 +167,9 @@ Ubiquitousse version string (currently "0.1.0").
    + + + @@ -145,13 +185,16 @@ Asset manager module, if available. + + +

    See also:

    @@ -164,13 +207,16 @@ Entity Component System, if available. + + +

    See also:

    @@ -183,13 +229,16 @@ Input management, if available. + + +

    See also:

    @@ -202,6 +251,9 @@ LDtk level import, if available. + + + @@ -221,13 +273,16 @@ Scene management, if available. + + +

    See also:

    @@ -240,13 +295,16 @@ Signal management, if available. + + +

    See also:

    @@ -259,13 +317,16 @@ Timer utilities, if available. + + +

    See also:

    @@ -278,13 +339,16 @@ Various useful functions, if available. + + +

    See also:

    @@ -296,7 +360,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-24 23:49:41 +Last updated 2021-12-25 17:06:47
    diff --git a/doc/topics/LICENSE.html b/doc/topics/LICENSE.html index efa0495..b15a307 100644 --- a/doc/topics/LICENSE.html +++ b/doc/topics/LICENSE.html @@ -4,7 +4,7 @@ Ubiquitousse reference - + @@ -40,8 +40,10 @@

    Modules

    @@ -58,7 +60,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-24 23:49:41 +Last updated 2021-12-25 17:06:47
    diff --git a/doc/topics/README.md.html b/doc/topics/README.md.html index e3123c6..d35c7bb 100644 --- a/doc/topics/README.md.html +++ b/doc/topics/README.md.html @@ -4,7 +4,7 @@ Ubiquitousse reference - + @@ -40,8 +40,10 @@

    Modules

    @@ -63,7 +65,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-24 23:49:41 +Last updated 2021-12-25 17:06:47
    diff --git a/ecs/ecs.can b/ecs/ecs.can index e9e26cd..cead0cf 100644 --- a/ecs/ecs.can +++ b/ecs/ecs.can @@ -1,19 +1,43 @@ ---- ubiquitousse.ecs --- Optional dependency: ubiquitousse.scene, to allow quick creation of ECS-based scenes. -local loaded, scene = pcall(require, (...):match("^(.-)ecs").."scene") -if not loaded then scene = nil end - ---- Entity Component System library, inspired by the excellent tiny-ecs. Main differences include: +--- ECS (entity compenent system) library +-- +-- Entity Component System library, inspired by the excellent tiny-ecs. Main differences include: +-- -- * ability to nest systems; -- * instanciation of systems for each world (no shared state); -- * adding and removing entities is done instantaneously -- * ability to add and remove components from entities after they were added to the world. +-- +-- No mandatory dependency. +-- Optional dependency: `ubiquitousse.scene`, to allow quick creation of ECS-based scenes. +-- +-- The module returns a table that contains several functions, `world` or `scene` are starting points +-- to create your world. +-- +-- @module ecs +-- @usage TODO +local loaded, scene = pcall(require, (...):match("^(.-)ecs").."scene") +if not loaded then scene = nil end + let ecs -- TODO: Implement a skip list for faster search. -- better control over system order: process, draw, methods? (for lag reasons and dependencies) -- more generic events? +-- TODO: :reorder (like refresh but update order) + +-- TODO: clarify documentation on entity tables and instanciated system table + +--- Entity table. +-- TODO +-- @section Entity + +--- Entity system table. +-- @doc entity + +--- @table entity +-- @field .. d + --- Recursively remove subsystems from a system. let recDestroySystems = (system) for i=#system.systems, 1, -1 do @@ -63,106 +87,193 @@ let copy = (a, b) end --- System fields and methods. +-- -- When they are added to a world, a new, per-world self table is created and used for every method call (which we call "instancied system"). --- Instancied systems can be retrieved in system.s or system.systems. --- Oh, the "world" is just the top-level system, behaving in exactly the same way as other systems. --- Every field defined below is optional unless written otherwise. +-- Instancied systems can be retrieved in `system.s` or `system.systems`. +-- +-- The "world" is just the top-level system, behaving in exactly the same way as other systems. +-- +-- Every field defined below is optional and can be accessed or redefined at any time, unless written otherwise. Though you would typically set them +-- when creating your system. +-- @type System let system_mt = { - --- Read-only after creation system options --- - -- I mean, you can try to change them afterwards. But, heh. + --- Modifiable fields + -- @doc modifiable --- Name of the system. - -- Used to create a field with the system's name in world.s and into each entity (the "entity's system table"). + -- Used to create a field with the system's name in `world.s` and into each entity (the "entity's system table") that's in this system. -- If not set, the entity will not have a system table. + -- + -- Do not change after system instanciation. + -- @ftype string + -- @ftype nil if no name name = nil, --- List of subsystems. -- On a instancied system, this is a list of the same subsystems, but instancied for this world. + -- + -- Do not change after system instanciation. + -- @ftype table + -- @ftype nil if no subsystem systems = nil, - --- Modifiable system options --- - - --- Returns true if the entity should be added to this system (and therefore its subsystems). - -- If this is a string or a table, it will be converted to a filter function on instanciation using ecs.any. - -- If this true, will accept every entity; if false, reject every entity. - -- Will only test entities when they are added; changing this after system creation will not affect entities already in the system. - -- By default, rejects everything. - filter = :(e) return false end, - --- Returns true if e1 <= e2. e1 and e2 are two entities. - -- Used to place the entity in the sorted entity list when it is added; changing this after system creation - -- will not change the order of entities already in the system. - compare = :(e1, e2) return true end, - - --- Called when adding an entity to the system. s is the entity's system table. - onAdd = :(s) end, - --- Called when removing an entity from the system. s is the entity's system table. - onRemove = :(s) end, - --- Called when the system is instancied, before any call to :onAddToWorld (including other systems in the world). - onInstance = :() end, - --- Called when the system is added to a world. - onAddToWorld = :(world) end, - --- Called when the system is removed from a world (i.e., the world is destroyed). - onRemoveFromWorld = :(world) end, - --- Called when the world is destroyed, after every call to :onRemoveFromWorld (including other systems in the world). - onDestroy = :() end, - --- Called when updating the system. - onUpdate = :(dt) end, - --- Called when drawing the system. - onDraw = :() end, - --- Called when updating the system, for every entity the system contains. Called after :onUpdate was called on the system. s is the entity's system table. - process = :(s, dt) end, - --- Called when drawing the system, for every entity the system contains. Called after :onDraw was called on the system. s is the entity's system table. - render = :(s) end, - --- If not false, the system will only update every interval seconds. + -- `false` by default. + -- @ftype number interval of time between each update + -- @ftype false to disable interval = false, --- The system and its susbsystems will only update if this is true. + -- `true` by default. + -- @ftype boolean active = true, --- The system and its subsystems will only draw if this is true. + -- `true` by default. + -- @ftype boolean visible = true, --- Defaults value to put into the entities's system table when they are added. Will recursively fill missing values. - -- When an entity is added to a system, a .entity field is always set in the system table, referring to the full entity table. + -- + -- When an entity is added to a system, a `.entity` field is always set in the system table, referring to the full entity table. + -- -- Changing this will not affect entities already in the system. + -- @ftype table + -- @ftype nil if no default default = nil, --- Defaults methods to assign to the entities's system table when they are added. - -- When calling the methods with entity.systemName:method(...), the method will actually receive the - -- arguments method(system, system table, ...). Methamethods are accepted. New methods can be + -- + -- When calling the methods with `entity.systemName:method(...)`, the method will actually receive the + -- arguments method(system, `system table, ...)`. Methamethods are accepted. New methods can be -- created anytime. + -- @ftype table + -- @ftype nil if no methods methods = nil, - --- Read-only system options --- + --- Callbacks. + -- + -- Functions that are called when something happens in the system. + -- Redefine them to change system behaviour. + -- @doc callbacks + + --- Called when checking if an entity should be added to this system. + -- Returns true if the entity should be added to this system (and therefore its subsystems). + -- + -- If this is a string or a table, it will be converted to a filter function on instanciation using ecs.any. + -- + -- If this true, will accept every entity; if false, reject every entity. + -- + -- Will only test entities when they are added; changing this after system creation will not affect entities already in the system. + -- + -- By default, rejects everything. + -- @callback + -- @tparam table e entity table to check + -- @treturn boolean true if entity should be added + filter = :(e) return false end, + --- Called when adding an entity to this system determining its order. + -- Returns true if e1 <= e2. e1 and e2 are two entities. + -- + -- Used to place the entity in the sorted entity list when it is added; changing this after system creation + -- will not change the order of entities already in the system. + -- + -- By default, entities are in the same order they were inserted. + -- @callback + -- @tparam table e1 entity table to check for inferiority + -- @tparam table e2 entity table to check for superiority + -- @treturn boolean true if e1 <= e2 + compare = :(e1, e2) return true end, + + --- Called when adding an entity to the system. + -- @callback + -- @tparam table s the entity's system table + onAdd = :(s) end, + --- Called when removing an entity from the system. + -- @callback + -- @tparam table s the entity's system table + onRemove = :(s) end, + --- Called when the system is instancied, before any call to `System:onAddToWorld` (including other systems in the world). + -- @callback + onInstance = :() end, + --- Called when the system is added to a world. + -- @callback + -- @tparam System world world system + onAddToWorld = :(world) end, + --- Called when the system is removed from a world (i.e., the world is destroyed). + -- @callback + -- @tparam System world world system + onRemoveFromWorld = :(world) end, + --- Called when the world is destroyed, after every call to `System:onRemoveFromWorld` (including other systems in the world). + -- @callback + onDestroy = :() end, + --- Called when updating the system. + -- @callback + -- @number dt delta-time since last update + onUpdate = :(dt) end, + --- Called when drawing the system. + -- @callback + onDraw = :() end, + --- Called when updating the system, for every entity the system contains. Called after `System:onUpdate` was called on the system. + -- @callback + -- @tparam table s the entity's system table + -- @number dt delta-time since last update + process = :(s, dt) end, + --- Called when drawing the system, for every entity the system contains. Called after `System:onDraw` was called on the system. + -- @callback + -- @tparam table s the entity's system table + render = :(s) end, + + --- Read-only fields + -- @doc ro --- The world the system belongs to. + -- @ftype System world + -- @ro world = nil, --- Number of entities in the system. + -- @ftype integer + -- @ro entityCount = 0, - --- Map of named systems in the world (not only subsystems). Same for every system from the same world. + --- Map of all named systems in the world (not only subsystems). Same for every system from the same world. + -- @ftype table {[system.name]=instanciedSystem, ...} + -- @ro s = nil, --- Private fields --- --- First element of the linked list of entities: { entity, next_element }. + -- @local _first = nil, --- Associative map of entities in the system and their previous linked list element (or true if first element). -- This make the list effectively a doubly linked list, but with easy access to the previous element using this map (and therefore O(1) deletion). + -- @local _previous = nil, --- Amount of time waited since last update (if interval is set). + -- @local _waited = 0, --- Metatable of entities' system table. -- Contains the methods defined in the methods field, wrapped to be called with the correct arguments, as well as a -- __index field (if not redefined in methods). + -- @local _methods_mt = nil, - --- Methods --- + --- Methods. + -- + -- Methods available on instancied system table. + -- @doc smethods --- Add entities to the system and its subsystems. + -- -- Will skip entities that are already in the system. + -- -- Entities are added to subsystems after they were succesfully added to their parent system. + -- -- If this is called on a subsystem instead of the world, be warned that this will bypass all the parent's systems filters. - -- Since :remove will not search for entities in systems where they should have been filtered out, the added entities will not be removed - -- when calling :remove on a parent system or the world. The entity can be removed by calling :remove on the system :add was called on. + -- + -- Since `System:remove` will not search for entities in systems where they should have been filtered out, the added entities will not be removed + -- when calling :remove on a parent system or the world. The entity can be removed by calling `System:remove` on the system `System:add` was called on. + -- -- Complexity: O(1) per unordered system, O(entityCount) per ordered system. + -- @tparam table e entity to add + -- @tparam table... ... other entities to add + -- @treturn e,... the function arguments add = :(e, ...) if e ~= nil and not @_previous[e] and @filter(e) then -- setup entity @@ -213,9 +324,14 @@ let system_mt = { end end, --- Refresh an entity's systems. - -- Behave similarly to :add, but if the entity is already in the system, instead of skipping it, it + -- + -- Behave similarly to `System:add`, but if the entity is already in the system, instead of skipping it, it -- will check for new and removed components and add and remove from (sub)systems accordingly. + -- -- Complexity: O(1) per system + add/remove complexity. + -- @tparam table e entity to refresh + -- @tparam table... ... other entities to refresh + -- @treturn e,... the function arguments refresh = :(e, ...) if e ~= nil then if not @_previous[e] then @@ -237,11 +353,19 @@ let system_mt = { end end, --- Remove entities to the system and its subsystems. + -- -- Will skip entities that are not in the system. + -- -- Entities are removed from subsystems before they are removed from their parent system. - -- If you intend to call this on a subsystem instead of the world, please read the warning in :add. + -- + -- If you intend to call this on a subsystem instead of the world, please read the warning in `System:add`. + -- -- Returns all removed entities. + -- -- Complexity: O(1) per system. + -- @tparam table e entity to remove + -- @tparam table... ... other entities to remove + -- @treturn e,... the function arguments remove = :(e, ...) if e ~= nil then if @_previous[e] then @@ -277,7 +401,11 @@ let system_mt = { end end, --- Returns true if every entity is in the system. + -- -- Complexity: O(1). + -- @tparam table e entity that may be in the system + -- @tparam table... ... other entities that may be in the system + -- @treturn boolean true if every entity is in the system has = :(e, ...) let has = e == nil or not not @_previous[e] if ... then @@ -287,6 +415,7 @@ let system_mt = { end end, --- Returns an iterator that iterate through the entties in this system. + -- @treturn iterator iterator over the entities in this system, in order iter = :() return nextEntity, { @_first } end, @@ -300,7 +429,9 @@ let system_mt = { end end, --- Try to update the system and its subsystems. Should be called on every game update. + -- -- Subsystems are updated after their parent system. + -- @number dt delta-time since last update update = :(dt) if @active then if @interval then @@ -324,6 +455,7 @@ let system_mt = { end end, --- Try to draw the system and its subsystems. Should be called on every game draw. + -- -- Subsystems are drawn after their parent system. draw = :() if @visible then @@ -419,9 +551,12 @@ let recCallOnAddToWorld = (world, systems) end --- ECS module. +-- @section end ecs = { --- Create and returns a world system based on a list of systems. -- The systems will be instancied for this world. + -- @tparam table,... ... list of (uninstancied) system tables + -- @treturn System the world system world = (...) let world = setmetatable({ filter = ecs.all(), @@ -435,6 +570,8 @@ ecs = { end, --- Returns a filter that returns true if, for every argument, a field with the same name exists in the entity. + -- @tparam string,... ... list of field names that must be in entity + -- @treturn function(e) that returns true if e has all the fields all = (...) if ... then let l = {...} @@ -452,6 +589,8 @@ ecs = { end, --- Returns a filter that returns true if one of the arguments if the name of a field in the entity. + -- @tparam string,... ... list of field names that may be in entity + -- @treturn function(e) that returns true if e has at leats one of the fields any = (...) if ... then let l = {...} @@ -468,7 +607,12 @@ ecs = { end end, - --- If uqt.scene is available, returns a new scene that will consist of a ECS world with the specified systems and entities. + --- If `uqt.scene` is available, returns a new scene that will consist of a ECS world with the specified systems and entities. + -- @require ubiquitousse.scene + -- @string name the name of the new scene + -- @tparam[opt={}] table systems list of systems to add to the world + -- @tparam[opt={}] table entities list of entities to add to the world + -- @treturn scene the new scene scene = (name, systems={}, entities={}) assert(scene, "ubiquitousse.scene unavailable") let s = scene.new(name) diff --git a/init.lua b/init.lua index 47b2129..2aa5691 100644 --- a/init.lua +++ b/init.lua @@ -45,6 +45,7 @@ -- *UPDATE*: I give up, currently in the process of admitting defat to LDoc and progressively porting all my documentation to it. -- Though I had to modify a few things to get LDoc to like me, so the documentation is generated using [my LDoc fork](https://github.com/Reuh/LDoc). -- +-- @module ubiquitousse -- @usage local ubiquitousse = require("ubiquitousse") local p = ... -- require path diff --git a/ldtk/ldtk.can b/ldtk/ldtk.can index 3e07df9..f66c00a 100644 --- a/ldtk/ldtk.can +++ b/ldtk/ldtk.can @@ -3,7 +3,7 @@ -- -- Every unit is in pixel in the API unless written otherwise. -- --- This modules returns a single function @{LDtk}(path). +-- This modules returns a single function, @{LDtk}(path). -- -- Requires LÖVE `love.graphics` (drawing Image, SpriteBatch, Quad). -- @@ -12,16 +12,18 @@ -- @usage -- local ldtk = require("ubiquitousse.ldtk") -- +-- -- load ldtk project file -- local project = ltdk("example.ldtk") -- +-- -- can define callbacks when loading: for example to setup entities defined in LDtk -- local callbacks = { -- onAddEntity = function(entity) -- -- handle entity... -- end -- } -- --- -- load every level --- for _, lvl in ipairs(project.levels) do lvl:load() end +-- -- load every level, with callbacks +-- for _, lvl in ipairs(project.levels) do lvl:load(callbacks) end -- -- function love.draw() -- -- draw every level @@ -412,7 +414,7 @@ let level_mt = { -- These callbacks should allow you to capture all the important elements needed to use the level, so you can hopefully -- integrate it into your current game engine easily. -- - -- @tab[opt] callbacks + -- @tparam[opt] table callbacks -- @require love load = :(callbacks={}) assert(@loaded == false, "level already loaded") @@ -454,7 +456,7 @@ let level_mt = { -- * `onAddIntTile(tile)` will be called for every new IntGrid tile unloaded, with the @{IntTile} as sole argument -- * `onAddEntity(entity)` will be called for every new entity unloaded, with the @{Entity} as sole argument -- - -- @tab[opt] callbacks + -- @tparam[opt] table callbacks unload = :(callbacks={}) assert(@loaded == true, "level not loaded") let onRemoveLayer = callbacks.onRemoveLayer @@ -581,11 +583,12 @@ let project_mt = { project_mt.__index = project_mt --- Custom fields. +-- TODO -- @section fields ---- Module. +--- LDtk module. -- `ubiquitousse.ldtk` returns a single function, @{LDtk}. --- @section module +-- @section end --- Load a LDtk project. -- @string path to LDtk project file (.ldtk)