From af3bd51cb3f22ef2871b329f03e97023186686a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Reuh=20Fildadut?= Date: Sun, 26 Dec 2021 18:13:32 +0100 Subject: [PATCH] Improve documentation --- README.md | 4 +- asset/README.md | 2 +- asset/asset.lua | 4 +- docs/index.html | 16 +- docs/modules/asset.html | 9 +- docs/modules/ecs.html | 579 ++++++++++++++------- docs/modules/ldtk.html | 919 ++++++++++++++++++++------------- docs/modules/scene.html | 72 ++- docs/modules/signal.html | 69 +-- docs/modules/timer.html | 232 ++++++--- docs/modules/ubiquitousse.html | 11 +- docs/modules/util.html | 9 +- docs/topics/LICENSE.html | 2 +- docs/topics/README.md.html | 6 +- ecs/README.md | 2 +- init.lua | 9 +- ldtk/ldtk.can | 127 ++++- scene/README.md | 2 +- scene/scene.lua | 32 +- signal/README.md | 2 +- signal/signal.can | 25 +- timer/README.md | 2 +- timer/timer.lua | 52 +- util/README.md | 2 +- util/util.lua | 4 +- 25 files changed, 1468 insertions(+), 725 deletions(-) diff --git a/README.md b/README.md index f31f933..069e893 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ Set of various libraries I use for game development, mainly with LÖVE. Nothing that hasn't been done before, but these are tailored to what I need. They can be used independently too. -Documentation is done in LDoc-like comments in source files, but LDoc doesn't really like how I structure my libraries so you can't really generate documentation with it. I'm currently trying to fix this; some modules already have a working LDoc documentation that you can read [here](https://reuh.github.io/ubiquitousse/index.html) or in the `docs/` directory. +You can find the documentation [here](https://reuh.github.io/ubiquitousse/index.html) or in the `docs/` directory. + +Documentation is done in LDoc-like comments in source files, but LDoc doesn't really like how I structure my libraries (and the fact I use [Candran](https://github.com/Reuh/candran)) so you will need my [LDoc fork](https://github.com/Reuh/LDoc) if you want to generate the documentation yourself. Whatever is currently on the master branch should be working and usable. Changelog, including breaking changes, are documented in commit messages. diff --git a/asset/README.md b/asset/README.md index bfe0f0f..930ba14 100644 --- a/asset/README.md +++ b/asset/README.md @@ -1,6 +1,6 @@ # ubiquitousse.asset -Asset manager library. +Asset manager library for Lua. You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/asset.html). diff --git a/asset/asset.lua b/asset/asset.lua index 91e3be0..b36b396 100644 --- a/asset/asset.lua +++ b/asset/asset.lua @@ -1,4 +1,4 @@ ---- Asset manager. +--- Asset manager for Lua. -- -- Loads asset and cache them. -- @@ -8,6 +8,8 @@ -- -- No dependencies. -- @module asset +-- @usage +-- TODO --- Asset manager. -- @type Asset diff --git a/docs/index.html b/docs/index.html index f7bbfd8..5360958 100644 --- a/docs/index.html +++ b/docs/index.html @@ -65,13 +65,11 @@ asset - Asset manager. + Asset manager for Lua. ecs - ECS (entity compenent system) library

- -

Entity Component System library, inspired by the excellent tiny-ecs. + ECS (entity compenent system) library for Lua. ldtk @@ -79,19 +77,19 @@ scene - Scene management. + Scene management for Lua game development. signal - Signal management. + Signal management for Lua. timer - Time related functions. + Timer management for Lua. util - Various functions useful for game developement. + Various functions useful for Lua game developement.

Topics

@@ -110,7 +108,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/asset.html b/docs/modules/asset.html index bb205c1..bd62940 100644 --- a/docs/modules/asset.html +++ b/docs/modules/asset.html @@ -60,7 +60,7 @@

Module asset

-

Asset manager.

+

Asset manager for Lua.

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.

@@ -68,6 +68,11 @@

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.

+

Usage:

+

Functions

@@ -329,7 +334,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/ecs.html b/docs/modules/ecs.html index 240aee7..93081ae 100644 --- a/docs/modules/ecs.html +++ b/docs/modules/ecs.html @@ -34,7 +34,7 @@

Contents

@@ -61,27 +61,56 @@

Module ecs

-

ECS (entity compenent system) library

- -

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

-

Main differences include:

+

ECS (entity compenent system) library for Lua.

+

Entity Component System library, inspired by the excellent tiny-ecs by bakpakin. +Main differences include:

-

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

+

And a fair amount of other quality-of-life features.

-

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

+

The goals of this library are similar in spirit to tiny-ecs: simple to use, flexible, and useful. +The more advanced features it provides relative to tiny-ecs are made so that you can completely ignore them +if you don’t use them.

+ +

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

+ +

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

Usage:

@@ -94,32 +123,27 @@ all (...) - Returns a filter that returns true if, for every argument, a field with the same name exists in the entity. + 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. + 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 objects

-

Entity system table.

+

Components.

- - - -
entity -

System objects

-

Modifiable fields

+

Modifiable fields.

@@ -131,23 +155,19 @@ - + - + - + - - - - - +
System.name
System.intervalIf not false, the system will only update every interval seconds.If not false, the system will only update every interval seconds.
System.activeThe system and its susbsystems will only update if this is true.The system and its susbsystems will only update if this is true.
System.visibleThe system and its subsystems will only draw if this is true.The 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.Defaults value to put into the entities’s system component when they are added.

Callbacks.

@@ -161,11 +181,11 @@ Called when adding an entity to this system determining its order. - System:onAdd (s) [callback] + System:onAdd (c, e) [callback] Called when adding an entity to the system. - System:onRemove (s) [callback] + System:onRemove (c, e) [callback] Called when removing an entity from the system. @@ -193,21 +213,25 @@ Called when drawing the system. - System:process (s, dt) [callback] + System:process (c, e, dt) [callback] Called when updating the system, for every entity the system contains. - System:render (s) [callback] + System:render (c, e) [callback] Called when drawing the system, for every entity the system contains. -

Read-only fields

+

Read-only fields.

+ + + + @@ -223,20 +247,24 @@ + + + + - - + + - + - + @@ -251,6 +279,14 @@ + + + + + + + + @@ -280,7 +316,7 @@ @@ -300,7 +336,7 @@ all (...)
- Returns a filter that returns true if, for every argument, a field with the same name exists in the entity. + Returns a filter that returns true if, for every argument, a field with the same name exists in the entity. @@ -319,7 +355,7 @@
    function(e) - that returns true if e has all the fields + that returns true if e has all the fields
@@ -331,7 +367,7 @@ any (...)
- Returns a filter that returns true if one of the arguments if the name of a field in the entity. + Returns a filter that returns true if one of the arguments if the name of a field in the entity. @@ -350,7 +386,7 @@
    function(e) - that returns true if e has at leats one of the fields + that returns true if e has at leats one of the fields
@@ -402,17 +438,28 @@
-

Entity table

+

Entity objects

- TODO + Entities are regular tables that get processed by Systems.

+ +

The idea is that entities should only contain data and no code; it’s the systems that are responsible for the actual processing + (but it’s your game, do as you want).

+ +

This data is referred to, and organized in, “components”.

-

Entity system table.

+

Components.

+ Entities are Lua tables, and thus contain key-values pairs: each one of these pairs is called a “component”. The data can be +whatever you want, and ideally each component should store the data for one singular aspect of the entity, for example its position, name, etc.

+

This library does not do any kind of special processing by itself on the entity tables and take them as is (no metatable, no methamethods, etc.), +so you are free to handle them as you want in your systems or elsewhere.

+

Since it’s relatively common for systems to only operate on a single component, as a shortcut the library often consider what it calls the “system component”: +that is, the component in the entity that has the same name as the system (if it exists).

@@ -425,47 +472,97 @@ +

Usage:

+
    + 
    -- example entity
+local entity = {
+	position = { x = 0, y = 52 }, -- a "position" component
+	sprite = newSprite("awesomeguy.png") -- a "sprite" component
+}
 
-
-    
    
-    
-    entity
-    
    
-    
    
-
-
-
+-- example "sprite" system
+local sprite = {
+	name = "sprite",
+	filter = "sprite", -- process entities that have a "sprite" component
+	-- systems callbacks that are called per-entity often give you the system component as an argument
+	-- the system component is the component with the same name as the system, thus here the sprite component
+	render = function(self, component, entity)
+		-- component == entity.sprite
+		component:draw()
+	end
+}
- - - - - - - -

System objects

- System fields and methods.

+ Systems and Worlds. +Systems are what do the processing on your entities. A system contains a list of entities; the entities in this list are selected +using a filter, and the system will only operate on those filtered entities.

-

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.

+

A system can also be created that do not accept any entity (filter = false, this is the default): such a system can still be +used to do processing that don’t need to be done per-entity but still behave like other systems (e.g. to do some static calculation each update).

-

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

+

The system also contains callbacks, these define the actual processing done on the system and its entities and you will want to redefine +at least one of them to make your system actually do something.

-

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. +

Then you can call System:update, System:draw, System:emit or System:callback at appropriate times and the system will call the +associated callbacks on itself and its entities, and then pass it to its subsystems. In practise you would likely only call these on +the world system, so the callbacks are correctly propagated to every single system in the world.

+ +

Systems are defined as regular tables with all the fields and methods you need in it. However, when a system is added to +a world, the table you defined is not used directly, but we use what we call an “instancied system”: think of it of an instance of your system +like if it were a class. +The instancied system will have a metatable set that gives it some methods and fields defined by the library on top of what you defined. +Modifying the instancied system will only modify this instance and not the original system you defined, so several instances of your system +can exist in different worlds (note that the original system is not copied on instancing; if you reference a table in the original system it will use the +original table directly).

+ +

Systems can have subsystems; that is a system that behave as an extension of their parent system. They only operates on the entities already +present in their parent subsystem, only update when their parent system updates, etc. You can thus organize your systems in a hierarchy to +avoid repeating your filters or allow controlling several system from a single parent system.

+ +

The top-level system is called the “world”; it behaves in exactly the same way as other systems, and accept every entity by default.

+

Usage:

+ 
local sprite = {
+	filter = { "sprite", "position" }, -- only operate on entities with "sprite" and "position" components
+	systems = { animated }, -- subsystems: they only operate on entities already filtered by this system (on top of their own filtering)
+
+	-- Called when an entity is added to this system.
+	onAdd = function(self, component, entity)
+		print("Added an entity, entity count in the system:", self.entityCount) -- self refer to the instancied system
+	end,
+
+	-- Called when the system is updated, for every entity the system
+	process = function(self, component, entity, dt)
+		-- processing...
+	end
+}
+
+local world = ecs.world(system) -- instanciate a world with the sprite system (and all its subsystems)
+
+-- Add an entity: doesn't pass the filtering, so nothing happens
+world:add {
+	name = "John"
+}
+
+-- Added to the sprite system! Call sprite:onAdd, and also try to add it to its subsystems
+world:add {
+	sprite = newSprite("example.png"),
+	position = { x=5, y=0 }
+}
+
+-- Trigger sprite:onUpdate and sprite:process callbacks
+world:update(dt)
-

Modifiable fields

+

Modifiable fields.

- - + Every field defined below is optional and can be accessed or redefined at any time, unless written otherwise. Though you would typically set them + before instanciating your systems.
@@ -486,8 +583,8 @@
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.

+ Used to create a field with the system’s name in world.s and determine the associated system component. + If not set, the system will not appear in world.s and gives nil instead of the system component in callbacks.

Do not change after system instanciation. @@ -536,7 +633,7 @@ System.interval

- If not false, the system will only update every interval seconds. + If not false, the system will only update every interval seconds. false by default. @@ -559,7 +656,7 @@ System.active
- The system and its susbsystems will only update if this is true. + The system and its susbsystems will only update if this is true. true by default. @@ -581,7 +678,7 @@ System.visible
- The system and its subsystems will only draw if this is true. + The system and its subsystems will only draw if this is true. true by default. @@ -603,17 +700,18 @@ System.default
- Defaults value to put into the entities’s system table when they are added. Will recursively fill missing values. + Defaults value to put into the entities’s system component when they are added.

+ +

If this is table, will recursively fill missing values. Metatables will be preserved during the copy but not copied themselves.

-

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. + Doesn’t have any effect if the system doesn’t have a name.

Type:

    -
  • table
    • +
  • any
  • nil if no default
@@ -624,32 +722,6 @@ -
-
- - 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.

@@ -676,11 +748,11 @@
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).

+ 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.

+

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.

@@ -703,7 +775,7 @@
    boolean - true if entity should be added + true if entity should be added
@@ -716,12 +788,12 @@
Called when adding an entity to this system determining its order. - Returns true if e1 <= e2. e1 and e2 are two entities.

+ Returns true if e1 <= e2 (i.e., if e1 should be processed before e2 in this system). 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. +

By default, new entities are added at the start of the list. @@ -731,11 +803,11 @@

Parameters:

  • e1 - table + Entity entity table to check for inferiority
  • e2 - table + Entity entity table to check for superiority
@@ -744,7 +816,7 @@
    boolean - true if e1 <= e2 + true if e1 <= e2
@@ -753,7 +825,7 @@
- System:onAdd (s) [callback] + System:onAdd (c, e) [callback]
Called when adding an entity to the system. @@ -765,9 +837,13 @@

Parameters:

    -
  • s - table - the entity’s system table +
  • c + Component + the entity’s system component +
    • +
  • e + Entity + the entity table
@@ -778,7 +854,7 @@
- System:onRemove (s) [callback] + System:onRemove (c, e) [callback]
Called when removing an entity from the system. @@ -790,9 +866,13 @@

Parameters:

    -
  • s - table - the entity’s system table +
  • c + Component + the entity’s system component +
    • +
  • e + Entity + the entity table
@@ -932,7 +1012,7 @@
- System:process (s, dt) [callback] + System:process (c, e, dt) [callback]
Called when updating the system, for every entity the system contains. Called after System:onUpdate was called on the system. @@ -944,9 +1024,13 @@

Parameters:

    -
  • s - table - the entity’s system table +
  • c + Component + the entity’s system component +
    • +
  • e + Entity + the entity table
  • dt number @@ -961,7 +1045,7 @@
- System:render (s) [callback] + System:render (c, e) [callback]
Called when drawing the system, for every entity the system contains. Called after System:onDraw was called on the system. @@ -973,9 +1057,13 @@

Parameters:

    -
  • s - table - the entity’s system table +
  • c + Component + the entity’s system component +
    • +
  • e + Entity + the entity table
@@ -985,10 +1073,9 @@
-

Read-only fields

+

Read-only fields.

- - + Fields available on instancied systems. Don’t modify them unless you like broken things.
@@ -1023,6 +1110,27 @@ + +
+ + System.w [read-only] +
+
+ Shortcut to System.world. + + +

Type:

+
    + System world +
+ + + + + + + +
@@ -1069,7 +1177,7 @@

Methods.

- Methods available on instancied system table. + Methods available on instancied systems.
@@ -1095,10 +1203,9 @@

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.

+

If this is called on a subsystem instead of the world, be warned that this will bypass all the parent’s systems filters. + If you do that, 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 System: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. @@ -1110,11 +1217,11 @@

Parameters:

  • e - table + Entity entity to add
  • ... - table... + Entity... other entities to add
@@ -1122,8 +1229,51 @@

Returns:

    - e,... - the function arguments + Entity,... + e,… the function arguments +
+ + + + + +
+ + System:remove (e, ...) +
+
+ Remove entities from 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.

+ +

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

Parameters:

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

Returns:

+
    + + Entity,... + e,… the function arguments
@@ -1150,11 +1300,11 @@

Parameters:

  • e - table + Entity entity to refresh
  • ... - table... + Entity... other entities to refresh
@@ -1162,8 +1312,8 @@

Returns:

    - e,... - the function arguments + Entity,... + e,… the function arguments
@@ -1171,21 +1321,16 @@
- - System:remove (e, ...) + + System:reorder (e, ...)
- Remove entities to the system and its subsystems.

+ Reorder an entity.

-

Will skip entities that are not in the system.

+

Will recalculate the entity position in the entity list for this 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. +

Complexity: O(entityCount) per system. @@ -1195,20 +1340,20 @@

Parameters:

  • e - table - entity to remove + Entity + entity to reorder
  • ... - table... - other entities to remove + Entity... + other entities to reorder

Returns:

    - e,... - the function arguments + Entity,... + e,… the function arguments
@@ -1220,7 +1365,7 @@ System:has (e, ...)
- Returns true if every entity is in the system.

+ Returns true if all these entities are in the system.

Complexity: O(1). @@ -1232,11 +1377,11 @@

Parameters:

  • e - table + Entity entity that may be in the system
  • ... - table... + Entity... other entities that may be in the system
@@ -1245,7 +1390,7 @@
    boolean - true if every entity is in the system + true if every entity is in the system
@@ -1257,7 +1402,7 @@ System:iter ()
- Returns an iterator that iterate through the entties in this system. + Returns an iterator that iterate through the entties in this system, in order. @@ -1269,7 +1414,7 @@
    iterator - iterator over the entities in this system, in order + iterator over the entities in this system
@@ -1340,6 +1485,92 @@ +
+
+ + System:callback (name, e, ...) +
+
+ Trigger a custom callback on a single entity.

+ +

This will call the System:name(c, e, …) method in this system and its subsystems, + if the method exists and the entity is in the system. c is the system component + associated with the current system, and e is the Entity.

+ +

Think of it as a way to perform custom callbacks issued from an entity event, similar to System:onAdd. + + + + + + +

Parameters:

+
    +
  • name + string + name of the callback +
    • +
  • e + Entity + the entity to perform the callback on +
    • +
  • ... + other arguments to pass to the callback +
    • +
+ + + + + +
+
+ + System:emit (name, ...) +
+
+ Emit an event on the system.

+ +

This will call the System:name(…) method in this system and its subsystems, + if the method exists.

+ +

Think of it as a way to perform custom callbacks issued from a general event, similar to System:onUpdate.

+ +

The called methods may return a string value to affect the event propagation behaviour:

+ +
    +
  • if a callback returns "stop", the event will not be propagated to the subsystems.
    • +
  • if a callback returns "capture", the event will not be propagated to the subsystems and +its sibling systems (i.e. completely stop the propagation of the event).
    • +
+ + +

"stop" would be for example used to disable some behaviour in the system and its subsystems (like active = false can + disable System:onUpdate behaviour on the system and its subsystems).

+ +

"capture" would be for example used to prevent other systems from handling the event (for example to make sure an + input event is handled only once by a single system). + + + + + + +

Parameters:

+
    +
  • name + string + name of the callback +
    • +
  • ... + other arguments to pass to the callback +
    • +
+ + + + +
@@ -1366,7 +1597,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/ldtk.html b/docs/modules/ldtk.html index 270ce3e..78164a0 100644 --- a/docs/modules/ldtk.html +++ b/docs/modules/ldtk.html @@ -34,13 +34,14 @@

Contents

@@ -108,6 +109,65 @@ end
System.world [read-only] The world the system belongs to.
System.w [read-only]Shortcut to System.world.
System.entityCount [read-only] Number of entities in the system.
Add entities to the system and its subsystems.
System:remove (e, ...)Remove entities from 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:reorder (e, ...)Reorder an entity.
System:has (e, ...)Returns true if every entity is in the system.Returns true if all these entities are in the system.
System:iter ()Returns an iterator that iterate through the entties in this system.Returns an iterator that iterate through the entties in this system, in order.
System:clear ()Try to draw the system and its subsystems.
System:callback (name, e, ...)Trigger a custom callback on a single entity.
System:emit (name, ...)Emit an event on the system.
System:destroy () Remove all the entities and subsystems in this system.
Load a LDtk project.
+

Entity objects

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Entity.layerLayer this entity belongs to.
Entity.identifierThe entity name.
Entity.xX position of the entity relative to the layer.
Entity.yY position of the entity relative to the layer.
Entity.widthThe entity width.
Entity.heightThe entity height.
Entity.sxScale factor on x axis relative to original entity size.
Entity.syScale factor on y axis relative to original entity size.
Entity.pivotXThe entity pivot point x position relative to the entity.
Entity.pivotYThe entity pivot point x position relative to the entity.
Entity.colorEntity color.
Entity.tileTile associated with the entity, if any.
Entity.fieldsMap of CustomFields of the entity.
Entity:draw ()Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

Tileset objects

@@ -131,7 +191,7 @@ end - + @@ -190,7 +250,7 @@ end
Layer.typeType of layer: IntGrid, Entities, Tiles or AutoLayer (string).Type of layer: IntGrid, Entities, Tiles or AutoLayer.
Layer.visible
- + @@ -225,7 +285,7 @@ end
Tile.layerLayer the tile belongs to.Layer the tile belongs to.
Tile.x
- + @@ -248,65 +308,6 @@ end
IntTile.layerLayer the IntTile belongs to.Layer the IntTile belongs to.
IntTile.xColor of the IntTile.
-

Entity objects

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Entity.layerLayer this entity belongs to.
Entity.identifierThe entity name.
Entity.xX position of the entity relative to the layer.
Entity.yY position of the entity relative to the layer.
Entity.widthThe entity width.
Entity.heightThe entity height.
Entity.sxScale factor on x axis relative to original entity size.
Entity.syScale factor on y axis relative to original entity size.
Entity.pivotXThe entity pivot point x position relative to the entity.
Entity.pivotYThe entity pivot point x position relative to the entity.
Entity.colorEntity color.
Entity.tileTile associated with the entity, if any.
Entity.fieldsMap of custom fields of the entity.
Entity:draw ()Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

Level objects

@@ -327,31 +328,31 @@ end - + - + - + - + - + - + - + @@ -369,6 +370,12 @@ end
Level.loadedWhether this level is currently loaded or not (boolean).Whether this level is currently loaded or not.
Level.identifierThe level name (string).The level name.
Level.xThe level x position (number).The level x position.
Level.yThe level y position (number).The level y position.
Level.widthThe level width (number).The level width.
Level.heightThe level height (number).The level height.
Level.fieldsMap of custom fields of the level (table).Map of CustomFields of the level (table).
Level.layersList of Levels in this project.
+

CustomFields objects

+ +
+

Type conversion.

+ +


@@ -407,6 +414,315 @@ end + + +

Entity objects

+ +
+ Entities are regular tables that get processed by Systems.

+ +

The idea is that entities should only contain data and no code; it’s the systems that are responsible for the actual processing + (but it’s your game, do as you want).

+ +

This data is referred to, and organized in, “components”. +

+
+
+ + Entity.layer +
+
+ Layer this entity belongs to. + + +

Type:

+
    + Layer +
+ + + + + + + + +
+
+ + Entity.identifier +
+
+ The entity name. + + +

Type:

+
    + string +
+ + + + + + + + +
+
+ + Entity.x +
+
+ X position of the entity relative to the layer. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.y +
+
+ Y position of the entity relative to the layer. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.width +
+
+ The entity width. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.height +
+
+ The entity height. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.sx +
+
+ Scale factor on x axis relative to original entity size. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.sy +
+
+ Scale factor on y axis relative to original entity size. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.pivotX +
+
+ The entity pivot point x position relative to the entity. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.pivotY +
+
+ The entity pivot point x position relative to the entity. + + +

Type:

+
    + number +
+ + + + + + + + +
+
+ + Entity.color +
+
+ Entity color. + + +

Type:

+
    + table {r,g,b} with r,g,b in [0-1] +
+ + + + + + + + +
+
+ + Entity.tile +
+
+ Tile associated with the entity, if any. Is a table { tileset = associated tileset object, quad = associated quad }. + quad is a LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }. + + +

Type:

+
    + table +
+ + + + + + + + +
+
+ + Entity.fields +
+
+ Map of CustomFields of the entity. + + +

Type:

+
    + CustomFields +
+ + + + + + + + +
+
+ + Entity:draw () +
+
+ Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

+ +

By default, this draws the tile associated with the entity if there is one, or a rectangle around the entity position otherwise. + +

Requires:

+
    + love +
+ + + + + + + + +

Tileset objects

@@ -474,6 +790,9 @@ end Level this layer belongs to. +

Type:

+ @@ -492,6 +811,9 @@ end The layer name. +

Type:

+ @@ -507,9 +829,12 @@ end Layer.type
- Type of layer: IntGrid, Entities, Tiles or AutoLayer (string). + Type of layer: IntGrid, Entities, Tiles or AutoLayer. +

Type:

+
    + string
@@ -528,6 +853,9 @@ end Whether the layer is visible or not. +

Type:

+
    + boolean
@@ -546,6 +874,9 @@ end The layer opacity (0-1). +

Type:

+
    + number
@@ -564,6 +895,9 @@ end The layer order: smaller order means it is on top. +

Type:

+
    + number
@@ -582,6 +916,9 @@ end X position of the layer relative to the level. +

Type:

+
    + number
@@ -600,6 +937,9 @@ end Y position of the layer relative to the level. +

Type:

+
    + number
@@ -618,6 +958,9 @@ end Size of the grid on this layer. +

Type:

+
    + number
@@ -636,6 +979,9 @@ end Width of the layer, in grid units. +

Type:

+
    + number
@@ -654,6 +1000,9 @@ end Height of the layer, in grid units. +

Type:

+
    + number
@@ -672,6 +1021,9 @@ end (Entities layer only) List of Entity in the layer. +

Type:

+
    + {Entity,...}
@@ -690,6 +1042,10 @@ end (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) List of Tiles in the layer. +

Type:

+
    +
  • {Tile,...}
    • +
  • nil if not applicable
@@ -708,6 +1064,10 @@ end (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) Tileset object associated with the layer. +

Type:

+
    +
  • Tileset
    • +
  • nil if not applicable
@@ -724,12 +1084,15 @@ end
(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) LÖVE SpriteBatch containing the layer. - nil if LÖVE not available.

Requires:

    love
+

Type:

+
    +
  • SpriteBatch
    • +
  • nil if LÖVE not available.
@@ -748,6 +1111,10 @@ end (IntGrid without AutoLayer rules layer only) list of IntTiles in the layer. +

Type:

+
    +
  • {IntTile,...}
    • +
  • nil if not applicable
@@ -766,7 +1133,7 @@ end

This represent the tiles from a Tiles, AutoLayer or IntGrid with AutoLayer rules layer.

-

Can be retrived from the tiles list or onAddTile level load callback. +

Can be retrived from the Layer.tiles list or onAddTile level load callback.

@@ -774,9 +1141,12 @@ end Tile.layer
- Layer the tile belongs to. + Layer the tile belongs to. +

Type:

+
    + Layer
@@ -795,6 +1165,9 @@ end X position of the tile relative to the layer. +

Type:

+
    + number
@@ -813,6 +1186,9 @@ end Y position of the tile relative to the layer. +

Type:

+
    + number
@@ -831,6 +1207,9 @@ end Whether the tile is flipped horizontally. +

Type:

+
    + boolean
@@ -849,6 +1228,9 @@ end Whether the tile is flipped vertically. +

Type:

+
    + boolean
@@ -867,6 +1249,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. +

Type:

+
    + {"tag",["tag"]=true,...}
@@ -885,6 +1270,9 @@ end Custom data associated with the tile, if any. +

Type:

+
    + string
@@ -901,9 +1289,12 @@ end
Quad associated with the tile (relative to the layer’s tileset). - LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }. +

Type:

+
    +
  • LÖVE Quad if LÖVE is available
    • +
  • table { x, y, width, height } if LÖVE not available
@@ -930,9 +1321,12 @@ end IntTile.layer
- Layer the IntTile belongs to. + Layer the IntTile belongs to. +

Type:

+
    + Layer
@@ -951,6 +1345,9 @@ end X position of the IntTile relative to the layer. +

Type:

+
    + number
@@ -969,6 +1366,9 @@ end Y position of the IntTile relative to the layer. +

Type:

+
    + number
@@ -987,6 +1387,9 @@ end Name of the IntTile. +

Type:

+
    + string
@@ -1005,6 +1408,9 @@ end Integer value of the IntTile. +

Type:

+
    + number
@@ -1023,275 +1429,9 @@ end Color of the IntTile. - - - - - - - - - -
-
-

Entity objects

- -
- Entity object.

- -

This represent an entity from an Entities layer.

- -

Can be retrived from the entities list or onAddEntity level load callback. -

-
-
- - Entity.layer -
-
- Layer this entity belongs to. - - - - - - - - - - - -
-
- - Entity.identifier -
-
- The entity name. - - - - - - - - - - - -
-
- - Entity.x -
-
- X position of the entity relative to the layer. - - - - - - - - - - - -
-
- - Entity.y -
-
- Y position of the entity relative to the layer. - - - - - - - - - - - -
-
- - Entity.width -
-
- The entity width. - - - - - - - - - - - -
-
- - Entity.height -
-
- The entity height. - - - - - - - - - - - -
-
- - Entity.sx -
-
- Scale factor on x axis relative to original entity size. - - - - - - - - - - - -
-
- - Entity.sy -
-
- Scale factor on y axis relative to original entity size. - - - - - - - - - - - -
-
- - Entity.pivotX -
-
- The entity pivot point x position relative to the entity. - - - - - - - - - - - -
-
- - Entity.pivotY -
-
- The entity pivot point x position relative to the entity. - - - - - - - - - - - -
-
- - Entity.color -
-
- Entity color. - - - - - - - - - - - -
-
- - Entity.tile -
-
- Tile associated with the entity, if any. Is a table { tileset = associated tileset object, quad = associated quad }. - quad is a LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }. - - - - - - - - - - - -
-
- - Entity.fields -
-
- Map of custom fields of the entity. - - - - - - - - - - - -
-
- - Entity:draw () -
-
- Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

- -

By default, this draws the tile associated with the entity if there is one, or a rectangle around the entity position otherwise. - -

Requires:

+

Type:

    - love -
+ table {r,g,b} with r,g,b in [0-1] @@ -1425,6 +1565,9 @@ end Project this level belongs to. +

Type:

+
    + Project
@@ -1440,9 +1583,12 @@ end Level.loaded
- Whether this level is currently loaded or not (boolean). + Whether this level is currently loaded or not. +

Type:

+
    + boolean
@@ -1458,9 +1604,12 @@ end Level.identifier
- The level name (string). + The level name. +

Type:

+
    + string
@@ -1476,9 +1625,12 @@ end Level.x
- The level x position (number). + The level x position. +

Type:

+
    + number
@@ -1494,9 +1646,12 @@ end Level.y
- The level y position (number). + The level y position. +

Type:

+
    + number
@@ -1512,9 +1667,12 @@ end Level.width
- The level width (number). + The level width. +

Type:

+
    + number
@@ -1530,9 +1688,12 @@ end Level.height
- The level height (number). + The level height. +

Type:

+
    + number
@@ -1548,9 +1709,12 @@ end Level.fields
- Map of custom fields of the level (table). + Map of CustomFields of the level (table). +

Type:

+
    + CustomFields
@@ -1569,6 +1733,9 @@ end List of Layers in the level (table). +

Type:

+
    + {Layer,...}
@@ -1587,7 +1754,7 @@ end Level background.

If there is a background image, background.image contains a table {image=image, x=number, y=number, sx=number, sy=number} - where image is the LÖVE image (or image filepath if LÖVE not available) x and y are the top-left position, + where image is the LÖVE image (or image filepath if LÖVE not available) x and y are the top-left position, and sx and sy the horizontal and vertical scale factors. @@ -1598,7 +1765,7 @@ end

Fields:

  • color - backrgound color + backrgound color {r,g,b} with r,g,b in [0-1]
  • image backrgound image information, if any @@ -1626,6 +1793,50 @@ end
    List of Levels in this project. +
+

Type:

+
    + {Level,...} +
+ + + + + + + + +
+
+

CustomFields objects

+ +
+ Custom fields: map of each field name to its value.

+ +

LDtk allows to defined custom fields in some places (Entity.fields, Level.fields). This library allows you to access them in a table that + map each field name to its value {["fieldName"]=value,…}. +

+
+
+

Type conversion.

+
+

Here is how the values are converted to Lua values:

+ + + + +
+
+ @@ -1644,7 +1855,7 @@ end
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/scene.html b/docs/modules/scene.html index d7efc46..079971f 100644 --- a/docs/modules/scene.html +++ b/docs/modules/scene.html @@ -60,7 +60,7 @@

Module scene

-

Scene management.

+

Scene management for Lua game development.

You can use use scenes to seperate the different states of your game: for example, a menu scene and a game scene. This module is fully implemented in Ubiquitousse and is mostly a “recommended way” of organising an Ubiquitousse-based game. However, you don’t have to use this if you don’t want to. ubiquitousse.scene handles all the differents Ubiquitousse-states and @@ -93,6 +93,11 @@

+

Usage:

+
    + 
    TODO
+
    +

Scene objects

@@ -103,11 +108,11 @@ Scene.timer - Scene-specific TimerRegistry, if uqt.time is available. + Scene-specific timer.TimerRegistry, if uqt.time is available. Scene.signal - Scene-specific SignalRegistry, if uqt.signal is available. + Scene-specific signal.SignalRegistry, if uqt.signal is available. Scene:enter (...) [callback] @@ -138,15 +143,15 @@ - + - + - + @@ -204,6 +209,9 @@ The scene name. +

Type:

+
    + string
@@ -219,9 +227,13 @@ Scene.timer
- Scene-specific TimerRegistry, if uqt.time is available. + Scene-specific timer.TimerRegistry, if uqt.time is available. +

Type:

+
    +
  • TimerRegistry
    • +
  • nil if uqt.time unavailable
@@ -237,9 +249,13 @@ Scene.signal
- Scene-specific SignalRegistry, if uqt.signal is available. + Scene-specific signal.SignalRegistry, if uqt.signal is available. +

Type:

+
    +
  • SignalRegistry
    • +
  • nil if uqt.signal unavailable
@@ -265,8 +281,7 @@

Parameters:

@@ -344,12 +359,11 @@

Parameters:

  • dt - - + number + the delta time
  • ... - - + additional arguments passed to scene:update
@@ -373,8 +387,7 @@

Parameters:

  • ... - - + additional arguments passed to scene:draw
@@ -392,9 +405,12 @@ current
- The current scene object. + The current Scene object. +

Type:

+
    + Scene
@@ -410,9 +426,13 @@ timer
- Shortcut for scene.current.timer. + Shortcut for scene.current.timer, the current scene timer.TimerRegistry. +

Type:

+
    +
  • TimerRegistry
    • +
  • nil if uqt.time unavailable
@@ -428,9 +448,13 @@ signal
- Shortcut for scene.current.signal. + Shortcut for scene.current.signal, the current scene timer.SignalRegistry. +

Type:

+
    +
  • SignalRegistry
    • +
  • nil if uqt.signal unavailable
@@ -449,6 +473,9 @@ The scene stack: list of scene, from the farest one to the nearest. +

Type:

+
    + {Scene,...}
@@ -468,6 +495,9 @@ Will search in the “scene” directory by default (prefix="scene."). Redefine it to fit your own ridiculous filesystem. +

Type:

+
    + string
@@ -628,7 +658,7 @@
  • dt number - the delta-time (milisecond) + the delta-time
  • ... arguments to pass to the scene’s update function after dt @@ -672,7 +702,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
    diff --git a/docs/modules/signal.html b/docs/modules/signal.html index 65c7c7b..46a3bc6 100644 --- a/docs/modules/signal.html +++ b/docs/modules/signal.html @@ -60,8 +60,14 @@

    Module signal

    -

    Signal management.

    -

    No dependency.

    +

    Signal management for Lua.

    +

    No dependency. + Optional dependency: LÖVE to hook into LÖVE events.

    +

    Usage:

    +
      + 
      TODO
+
      +

    Module

    @@ -72,7 +78,7 @@
- @@ -149,7 +155,7 @@ event
-

SignalRegistry which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry +

SignalRegistry which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry if avaible.

For example, every ubiquitousse module with a “update” function will bind it to the “update” signal in the registry; @@ -166,6 +172,9 @@ +

Type:

+
    + SignalRegistry
@@ -215,6 +224,9 @@ Map of signals to list of listeners. +

Type:

+
    + {["name"]={fn,...}}
@@ -240,16 +252,16 @@

Parameters:

  • name - - + string + the name of the signal
  • fn - - + function + the function to bind to the signal
  • ... - - + function,... + other function to bind to the signal
@@ -273,16 +285,16 @@

Parameters:

  • name - - + string + the name of the signal
  • fn - - + function + the function to unbind to the signal
  • ... - - + function,... + other function to unbind to the signal
@@ -306,8 +318,8 @@

Parameters:

  • name - - + string + the name of the signal
@@ -331,16 +343,16 @@

Parameters:

  • name - - + string + the name of the signal
  • sourceFn - - + function + the function currently bound to the signal
  • destFn - - + function + the function that will replace the previous one
@@ -382,12 +394,11 @@

Parameters:

  • name - - + string + the name of the signal
  • ... - - + arguments to pass to the functions bound to this signal
@@ -403,7 +414,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/timer.html b/docs/modules/timer.html index 29aebb9..d170bd9 100644 --- a/docs/modules/timer.html +++ b/docs/modules/timer.html @@ -62,8 +62,13 @@

Module timer

-

Time related functions.

+

Timer management for Lua.

No dependency.

+

Usage:

+
    + 
    TODO
+
    +

Module

@@ -84,19 +89,19 @@

Timer objects

currentThe current scene object.The current Scene object.
timerShortcut for scene.current.timer.Shortcut for scene.current.timer, the current scene timer.TimerRegistry.
signalShortcut for scene.current.signal.Shortcut for scene.current.signal, the current scene timer.SignalRegistry.
stack
eventSignalRegistry which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry + SignalRegistry which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry if avaible.
- + - + - + - +
Timer:after (time)Timer:after ([, time]) Wait time seconds before running the function.
Timer:every (time)Timer:every ([, time]) Run the function every time millisecond.
Timer:times (count)Timer:times ([, count]) The function will not execute more than count times.
Timer:during (time)Timer:during ([, time]) The timer will be active for a time duration.
@@ -193,7 +198,7 @@

TweenTimer objects

- +
r.chain (_, duration_, tbl_, to_, method_)r:chain (duration, tbl, to[, method="linear"]) Creates another tween which will be initialized when the current one ends.
@@ -264,7 +269,7 @@
    Timer - the object + the new timer
@@ -326,7 +331,7 @@
- Timer:after (time) + Timer:after ([, time])
Wait time seconds before running the function. @@ -340,11 +345,18 @@

Parameters:

  • time - - + number + duration to wait + (optional)
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -352,7 +364,7 @@
- Timer:every (time) + Timer:every ([, time])
Run the function every time millisecond. @@ -366,11 +378,18 @@

Parameters:

  • time - - + number + duration between execution + (optional)
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -378,7 +397,7 @@
- Timer:times (count) + Timer:times ([, count])
The function will not execute more than count times. @@ -392,11 +411,18 @@

Parameters:

  • count - - + number + number of times + (optional)
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -404,7 +430,7 @@
- Timer:during (time) + Timer:during ([, time])
The timer will be active for a time duration. @@ -418,11 +444,18 @@

Parameters:

  • time - - + number + duration of execution + (optional)
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -464,11 +497,17 @@

Parameters:

  • func - - + function + function that returns true if condition is verified
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -490,11 +529,17 @@

Parameters:

  • func - - + function + function that returns true if condition is verified
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -517,11 +562,17 @@

Parameters:

  • func - - + function + function that returns true if condition is verified
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -543,11 +594,17 @@

Parameters:

  • func - - + function + function that returns true if condition is verified
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -585,6 +642,12 @@ +

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -603,6 +666,12 @@ +

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -621,6 +690,12 @@ +

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -641,11 +716,17 @@

Parameters:

  • time - - + number + duration to skip
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -685,11 +766,17 @@

Parameters:

  • func - - + function + function to call when timer start
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -710,11 +797,17 @@

Parameters:

  • func - - + function + function to call at each timer update
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -735,11 +828,17 @@

Parameters:

  • func - - + function + function to call when timer ends
+

Returns:

+
    + + Timer + the same timer, for chaining method calls +
@@ -780,8 +879,8 @@

Parameters:

  • func - - + function + function called by the chained timer
@@ -789,8 +888,7 @@
    Timer - - + the new timer
@@ -917,11 +1015,17 @@

Parameters:

  • func - - + function + function called by the timer
+

Returns:

+
    + + Timer + the new timer +
@@ -960,6 +1064,12 @@ +

Returns:

+
    + + TweenTimer + the new timer +
@@ -991,13 +1101,13 @@
- - r.chain (_, duration_, tbl_, to_, method_) + + r:chain (duration, tbl, to[, method="linear"])
Creates another tween which will be initialized when the current one ends. If tbl and/or method are not specified, the values from the current tween will be used. - Returns the new tween. + Returns the new tween timer. @@ -1006,25 +1116,22 @@

Parameters:

    -
  • _ - - +
  • duration + number + tween duration (seconds)
    • -
  • duration_ - - +
  • tbl + table + the table containing the values to tween
    • -
  • tbl_ - - +
  • to + table + the new values
    • -
  • to_ - - -
    • -
  • method_ - - +
  • method + string/function + tweening method (string name or the actual function(time, start, change, duration)) + (default "linear")
@@ -1032,8 +1139,7 @@
    TweenTimer - - + the new timer
@@ -1047,7 +1153,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 23:19:42 +Last updated 2021-12-26 18:13:01
diff --git a/docs/modules/ubiquitousse.html b/docs/modules/ubiquitousse.html index 3859ca8..a653206 100644 --- a/docs/modules/ubiquitousse.html +++ b/docs/modules/ubiquitousse.html @@ -103,12 +103,9 @@ -

Regarding the documentation: Ubiquitousse used LDoc/LuaDoc styled-comments, but since LDoc hates me and my code, the - generated result is complete garbage, so please read the documentation directly in the comments here until fix this. - Stuff you're interested in starts with triple – (e.g., “—– This functions saves the world”).

- -

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.

+

Regarding the documentation: Ubiquitousse uses LDoc/LuaDoc styled-comments, but since LDoc hates me and my code, the + generated result is mostly garbage, so to generate the documentation you will need to use my LDoc fork + which I modified to force LDoc to like me.

Usage:

    local ubiquitousse = require("ubiquitousse")
@@ -364,7 +361,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2021-12-25 23:19:42 
+Last updated 2021-12-26 18:13:01 
 
     
  
 
diff --git a/docs/modules/util.html b/docs/modules/util.html
index 4766df8..84ca62e 100644
--- a/docs/modules/util.html
+++ b/docs/modules/util.html
@@ -59,8 +59,13 @@
 
    
 
 
    Module util
    
-
    Various functions useful for game developement.
    
+
    Various functions useful for Lua game developement.
    
 
     No dependency.
    
+    
    Usage:
    
+    
      
+        
      TODO
+
      
+    
    
 
 
 
    Functions 
    
@@ -779,7 +784,7 @@
 
     
 
    
 generated by LDoc 1.4.6
-Last updated 2021-12-25 23:19:42 
+Last updated 2021-12-26 18:13:01 
 
     
  
 
diff --git a/docs/topics/LICENSE.html b/docs/topics/LICENSE.html
index 67db8be..c9df972 100644
--- a/docs/topics/LICENSE.html
+++ b/docs/topics/LICENSE.html
@@ -64,7 +64,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2021-12-25 23:19:42 
+Last updated 2021-12-26 18:13:01 
 
     
  
 
diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html
index 03b39e7..312b394 100644
--- a/docs/topics/README.md.html
+++ b/docs/topics/README.md.html
@@ -58,7 +58,9 @@
 
 
    Set of various libraries I use for game development, mainly with LÖVE. Nothing that hasn’t been done before, but these are tailored to what I need. They can be used independently too.
    
 
-
    Documentation is done in LDoc-like comments in source files, but LDoc doesn’t really like how I structure my libraries so you can’t really generate documentation with it. I'm currently trying to fix this; some modules already have a working LDoc documentation that you can read here or in the docs/ directory.
    
+
    You can find the documentation here or in the docs/ directory.
    
+
+
    Documentation is done in LDoc-like comments in source files, but LDoc doesn’t really like how I structure my libraries (and the fact I use Candran) so you will need my LDoc fork if you want to generate the documentation yourself.
    
 
 
    Whatever is currently on the master branch should be working and usable. Changelog, including breaking changes, are documented in commit messages.
    
 
@@ -69,7 +71,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2021-12-25 23:19:42 
+Last updated 2021-12-26 18:13:01 
 
     
  
 
diff --git a/ecs/README.md b/ecs/README.md
index da82cb7..2dd22b4 100644
--- a/ecs/README.md
+++ b/ecs/README.md
@@ -1,6 +1,6 @@
 # ubiquitousse.ecs
 
-ECS (entity compenent system) library.
+ECS (entity compenent system) library for Lua.
 
 You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/ecs.html).
 
diff --git a/init.lua b/init.lua
index 82d2497..6c91ec6 100644
--- a/init.lua
+++ b/init.lua
@@ -38,12 +38,9 @@
 -- * CamelCase for class names.
 -- * lowerCamelCase is expected for everything else.
 --
--- Regarding the documentation: Ubiquitousse used LDoc/LuaDoc styled-comments, but since LDoc hates me and my code, the
--- generated result is complete garbage, so please read the documentation directly in the comments here until fix this.
--- Stuff you're interested in starts with triple - (e.g., "--- This functions saves the world").
---
--- *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).
+-- Regarding the documentation: Ubiquitousse uses LDoc/LuaDoc styled-comments, but since LDoc hates me and my code, the
+-- generated result is mostly garbage, so to generate the documentation you will need to use my [LDoc fork](https://github.com/Reuh/LDoc)
+-- which I modified to force LDoc to like me.
 --
 -- @module ubiquitousse
 -- @usage local ubiquitousse = require("ubiquitousse")
diff --git a/ldtk/ldtk.can b/ldtk/ldtk.can
index a56ce30..cf019b3 100644
--- a/ldtk/ldtk.can
+++ b/ldtk/ldtk.can
@@ -191,39 +191,58 @@ let layer_mt = {
 	_init = (layer, level, order, callbacks)
 		let gridSize = layer.__gridSize
 		let t = {
-			--- @{Level} this layer belongs to.
+			--- `Level` this layer belongs to.
+			-- @ftype Level
 			level = level,
 			--- The layer name.
+			-- @ftype string
 			identifier = layer.__identifier,
-			--- Type of layer: IntGrid, Entities, Tiles or AutoLayer (string).
+			--- Type of layer: IntGrid, Entities, Tiles or AutoLayer.
+			-- @ftype string
 			type = layer.__type,
 			--- Whether the layer is visible or not.
+			-- @ftype boolean
 			visible = layer.visible,
 			--- The layer opacity (0-1).
+			-- @ftype number
 			opacity = layer.opacity,
 			--- The layer order: smaller order means it is on top.
+			-- @ftype number
 			order = order,
 			--- X position of the layer relative to the level.
+			-- @ftype number
 			offsetX = layer.__pxTotalOffsetX,
 			--- Y position of the layer relative to the level.
+			-- @ftype number
 			offsetY = layer.__pxTotalOffsetY,
 			--- Size of the grid on this layer.
+			-- @ftype number
 			gridSize = gridSize,
 			--- Width of the layer, in grid units.
+			-- @ftype number
 			gridWidth = layer.__cWid,
 			--- Height of the layer, in grid units.
+			-- @ftype number
 			gridHeight = layer.__cHei,
-			--- _(Entities layer only)_ List of @{Entity} in the layer.
+			--- _(Entities layer only)_ List of `Entity` in the layer.
+			-- @ftype {Entity,...}
 			entities = nil,
-			--- _(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only)_ List of @{Tile}s in the layer.
+			--- _(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only)_ List of `Tile`s in the layer.
+			-- @ftype {Tile,...}
+			-- @ftype nil if not applicable
 			tiles = nil,
-			--- _(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.
+			-- @ftype Tileset
+			-- @ftype nil if not applicable
 			tileset = nil,
 			--- _(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only)_ [LÖVE SpriteBatch](https://love2d.org/wiki/SpriteBatch) containing the layer.
-			-- nil if LÖVE not available.
+			-- @ftype SpriteBatch
+			-- @ftype nil if LÖVE not available.
 			-- @require love
 			spritebatch = nil,
-			--- _(IntGrid without AutoLayer rules layer only)_ list of @{IntTile}s in the layer.
+			--- _(IntGrid without AutoLayer rules layer only)_ list of `IntTile`s in the layer.
+			-- @ftype {IntTile,...}
+			-- @ftype nil if not applicable
 			intTiles = nil,
 		}
 		-- Layers with an associated tileset (otherwise ignore as there is nothing to draw) (Tiles, AutoLayer & IntGrid with AutoLayer rules)
@@ -242,26 +261,34 @@ let layer_mt = {
 				--
 				-- This represent the tiles from a Tiles, AutoLayer or IntGrid with AutoLayer rules layer.
 				--
-				-- Can be retrived from the @{tiles} list or `onAddTile` level load callback.
+				-- Can be retrived from the `Layer.tiles` list or `onAddTile` level load callback.
 				--
 				-- @type Tile
 				let tile = {
-					--- Layer the tile belongs to.
+					--- `Layer` the tile belongs to.
+					-- @ftype Layer
 					layer = t,
 					--- X position of the tile relative to the layer.
+					-- @ftype number
 					x = x,
 					--- Y position of the tile relative to the layer.
+					-- @ftype number
 					y = y,
 					--- Whether the tile is flipped horizontally.
+					-- @ftype boolean
 					flipX = false,
 					--- Whether the tile is flipped vertically.
+					-- @ftype boolean
 					flipY = false,
 					--- Tags associated with the tile: can be used either as a list of tags or a map of activated tags tags[name] == true.
+					-- @ftype {"tag",["tag"]=true,...}
 					tags = tilesetData[tl.t].tags,
 					--- Custom data associated with the tile, if any.
+					-- @ftype string
 					data = tilesetData[tl.t].data,
 					--- Quad associated with the tile (relative to the layer's tileset).
-					-- LÖVE Quad if LÖVE is available, otherwise a table `{ x, y, width, height }`.
+					-- @ftype LÖVE Quad if LÖVE is available
+					-- @ftype table { x, y, width, height } if LÖVE not available
 					quad = quad
 				}
 				if tl.f == 1 or tl.f == 3 then
@@ -295,17 +322,23 @@ let layer_mt = {
 					--
 					-- @type IntTile
 					let tile = {
-						--- Layer the IntTile belongs to.
+						--- `Layer` the IntTile belongs to.
+						-- @ftype Layer
 						layer = t,
 						--- X position of the IntTile relative to the layer.
+						-- @ftype number
 						x = x,
 						--- Y position of the IntTile relative to the layer.
+						-- @ftype number
 						y = y,
 						--- Name of the IntTile.
+						-- @ftype string
 						identifier = values[tl].identifier,
 						--- Integer value of the IntTile.
+						-- @ftype number
 						value = tl,
 						--- Color of the IntTile.
+						-- @ftype table {r,g,b} with r,g,b in [0-1]
 						color = values[tl].color
 					}
 					table.insert(t.intTiles, tile)
@@ -327,32 +360,45 @@ let layer_mt = {
 				--
 				-- @type Entity
 				let entity = {
-					--- @{Layer} this entity belongs to.
+					--- `Layer` this entity belongs to.
+					-- @ftype Layer
 					layer = t,
 					--- The entity name.
+					-- @ftype string
 					identifier = e.__identifier,
 					--- X position of the entity relative to the layer.
+					-- @ftype number
 					x = e.px[1],
 					--- Y position of the entity relative to the layer.
+					-- @ftype number
 					y = e.px[2],
 					--- The entity width.
+					-- @ftype number
 					width = e.width,
 					--- The entity height.
+					-- @ftype number
 					height = e.height,
 					--- Scale factor on x axis relative to original entity size.
+					-- @ftype number
 					sx = e.width / entityDef.width,
 					--- Scale factor on y axis relative to original entity size.
+					-- @ftype number
 					sy = e.height / entityDef.height,
 					--- The entity pivot point x position relative to the entity.
+					-- @ftype number
 					pivotX = e.__pivot[1] * e.width,
 					--- The entity pivot point x position relative to the entity.
+					-- @ftype number
 					pivotY = e.__pivot[2] * e.height,
 					--- Entity color.
+					-- @ftype table {r,g,b} with r,g,b in [0-1]
 					color = entityDef.color,
 					--- Tile associated with the entity, if any. Is a table { tileset = associated tileset object, quad = associated quad }.
 					-- `quad` is a LÖVE Quad if LÖVE is available, otherwise a table `{ x, y, width, height }`.
+					-- @ftype table
 					tile = nil,
-					--- Map of custom fields of the entity.
+					--- Map of `CustomFields` of the entity.
+					-- @ftype CustomFields
 					fields = getFields(e.fieldInstances),
 					--- Called for the entity when drawing the associated entity layer (you will likely want to redefine it).
 					--
@@ -489,30 +535,39 @@ let level_mt = {
 
 	_init = (level, project)
 		let t = {
-			--- @{Project} this level belongs to.
+			--- `Project` this level belongs to.
+			-- @ftype Project
 			project = project,
-			--- Whether this level is currently loaded or not (boolean).
+			--- Whether this level is currently loaded or not.
+			-- @ftype boolean
 			loaded = false,
-			--- The level name (string).
+			--- The level name.
+			-- @ftype string
 			identifier = level.identifier,
-			--- The level x position (number).
+			--- The level x position.
+			-- @ftype number
 			x = level.worldX,
-			--- The level y position (number).
+			--- The level y position.
+			-- @ftype number
 			y = level.worldY,
-			--- The level width (number).
+			--- The level width.
+			-- @ftype number
 			width = level.pxWid,
-			--- The level height (number).
+			--- The level height.
+			-- @ftype number
 			height = level.pxHei,
-			--- Map of custom fields of the level (table).
+			--- Map of `CustomFields` of the level (table).
+			-- @ftype CustomFields
 			fields = getFields(level.fieldInstances),
-			--- List of @{Layer}s in the level (table).
+			--- List of `Layer`s in the level (table).
+			-- @ftype {Layer,...}
 			layers = nil,
 			--- Level background.
 			--
 			-- If there is a background image, `background.image` contains a table `{image=image, x=number, y=number, sx=number, sy=number}`
 			-- where `image` is the LÖVE image (or image filepath if LÖVE not available) `x` and `y` are the top-left position,
 			-- and `sx` and `sy` the horizontal and vertical scale factors.
-			-- @field color backrgound color
+			-- @field color backrgound color {r,g,b} with r,g,b in [0-1]
 			-- @field image backrgound image information, if any
 			background = {
 				color = parseColor(level.__bgColor),
@@ -536,7 +591,8 @@ let project_mt = {
 	_init = (project, directory)
 		assert(project.jsonVersion == "0.9.3", "map made for LDtk version %s":format(project.jsonVersion))
 		let t = {
-			--- List of @{Level}s in this project.
+			--- List of `Level`s in this project.
+			-- @ftype {Level,...}
 			levels = nil,
 
 			-- private
@@ -608,9 +664,26 @@ let project_mt = {
 }
 project_mt.__index = project_mt
 
---- Custom fields.
--- TODO
--- @section fields
+--- Custom fields: map of each field name to its value.
+--
+-- LDtk allows to defined custom fields in some places (`Entity.fields`, `Level.fields`). This library allows you to access them in a table that
+-- map each field name to its value `{["fieldName"]=value,...}`.
+--
+-- @type CustomFields
+
+--- Type conversion.
+--
+-- Here is how the values are converted to Lua values:
+--
+-- * Integers, Floats are converted into a Lua number.
+-- * Booleans are converted into a Lua boolean.
+-- * Strings, Multilines are converted in a Lua string.
+-- * Enum are converted into a Lua string giving the currently selected enum value.
+-- * Filepath are converted into a Lua string giving the file path.
+-- * Arrays are converted into a Lua table with the elements in it as a list.
+-- * Points are converted into a Lua table with the fields `x` and `y`: `{ x=number, y=number }`.
+-- * Colors are converted into a Lua table with the red, green and blue components in [0-1] as a list: `{r,g,b}`.
+-- @doc conversion
 
 --- LDtk module.
 -- `ubiquitousse.ldtk` returns a single function, @{LDtk}.
diff --git a/scene/README.md b/scene/README.md
index 9048a98..de03e54 100644
--- a/scene/README.md
+++ b/scene/README.md
@@ -1,6 +1,6 @@
 # ubiquitousse.scene
 
-Scene management library.
+Scene management library for Lua game development.
 
 You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/scene.html).
 
diff --git a/scene/scene.lua b/scene/scene.lua
index 9ae277c..5ce10d4 100644
--- a/scene/scene.lua
+++ b/scene/scene.lua
@@ -1,4 +1,4 @@
---- Scene management.
+--- Scene management for Lua game development.
 --
 -- You can use use scenes to seperate the different states of your game: for example, a menu scene and a game scene.
 -- This module is fully implemented in Ubiquitousse and is mostly a "recommended way" of organising an Ubiquitousse-based game.
@@ -23,6 +23,8 @@
 -- * ubiquitousse.timer (to provide each scene a timer registry).
 -- * ubiquitousse.signal (to bind to update and draw signal in signal.event).
 -- @module scene
+-- @usage
+-- TODO
 local loaded, signal = pcall(require, (...):match("^(.-)scene").."signal")
 if not loaded then signal = nil end
 local loaded, timer = pcall(require, (...):match("^(.-)scene").."timer")
@@ -32,12 +34,18 @@ if not loaded then timer = nil end
 -- @type Scene
 local _ = {
 	--- The scene name.
+	-- @ftype string
 	name = name or "unamed",
-	--- Scene-specific TimerRegistry, if uqt.time is available.
+	--- Scene-specific `timer.TimerRegistry`, if uqt.time is available.
+	-- @ftype TimerRegistry
+	-- @ftype nil if uqt.time unavailable
 	timer = timer and timer.new(),
-	--- Scene-specific SignalRegistry, if uqt.signal is available.
+	--- Scene-specific `signal.SignalRegistry`, if uqt.signal is available.
+	-- @ftype SignalRegistry
+	-- @ftype nil if uqt.signal unavailable
 	signal = signal and signal.new(),
 	--- Called when entering a scene.
+	-- @param ... additional arguments passed to `scene:switch` or `scene:push`
 	-- @callback
 	enter = function(self, ...) end,
 	--- Called when exiting a scene, and not expecting to come back (scene may be unloaded).
@@ -50,9 +58,12 @@ local _ = {
 	-- @callback
 	resume = function(self) end,
 	--- Called on each update on the current scene.
+	-- @tparam number dt the delta time
+	-- @param ... additional arguments passed to `scene:update`
 	-- @callback
 	update = function(self, dt, ...) end,
 	--- Called on each draw on the current scene.
+	-- @param ... additional arguments passed to `scene:draw`
 	-- @callback
 	draw = function(self, ...) end
 }
@@ -62,19 +73,26 @@ local _ = {
 
 local scene
 scene = {
-	--- The current scene object.
+	--- The current `Scene` object.
+	-- @ftype Scene
 	current = nil,
 
-	--- Shortcut for scene.current.timer.
+	--- Shortcut for scene.current.timer, the current scene `timer.TimerRegistry`.
+	-- @ftype TimerRegistry
+	-- @ftype nil if uqt.time unavailable
 	timer = nil,
-	--- Shortcut for scene.current.signal.
+	--- Shortcut for scene.current.signal, the current scene `timer.SignalRegistry`.
+	-- @ftype SignalRegistry
+	-- @ftype nil if uqt.signal unavailable
 	signal = nil,
 
 	--- The scene stack: list of scene, from the farest one to the nearest.
+	-- @ftype {Scene,...}
 	stack = {},
 
 	--- A prefix for scene modules names.
 	-- Will search in the "scene" directory by default (`prefix="scene."`). Redefine it to fit your own ridiculous filesystem.
+	-- @ftype string
 	prefix = "scene.",
 
 	--- Creates and returns a new Scene object.
@@ -156,7 +174,7 @@ scene = {
 
 	--- Update the current scene.
 	-- Should be called at every game update. If ubiquitousse.signal is available, will be bound to the "update" signal in signal.event.
-	-- @tparam number dt the delta-time (milisecond)
+	-- @tparam number dt the delta-time
 	-- @param ... arguments to pass to the scene's update function after dt
 	update = function(dt, ...)
 		if scene.current then
diff --git a/signal/README.md b/signal/README.md
index 7642e54..11fbd76 100644
--- a/signal/README.md
+++ b/signal/README.md
@@ -1,6 +1,6 @@
 # ubiquitousse.signal
 
-Signal management library.
+Signal management library for Lua.
 
 You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/signal.html).
 
diff --git a/signal/signal.can b/signal/signal.can
index bad9745..4cb1b3a 100644
--- a/signal/signal.can
+++ b/signal/signal.can
@@ -1,7 +1,10 @@
---- Signal management.
+--- Signal management for Lua.
 --
 -- No dependency.
+-- Optional dependency: LÖVE to hook into LÖVE events.
 -- @module signal
+-- @usage
+-- TODO
 
 --- Signal registry.
 --
@@ -9,20 +12,27 @@
 -- @type SignalRegistry
 let registry_mt = {
 	--- Map of signals to list of listeners.
+	-- @ftype {["name"]={fn,...}}
 	signals = {},
 
 	--- Bind one or several functions to a signal name.
+	-- @tparam string name the name of the signal
+	-- @tparam function fn the function to bind to the signal
+	-- @tparam function,... ... other function to bind to the signal
 	bind = :(name, fn, ...)
 		if not @signals[name] then
 			@signals[name] = {}
 		end
 		table.insert(@signals[name], fn)
 		if ... then
-			return @bind(name, ...)
+			@bind(name, ...)
 		end
 	end,
 
 	--- Unbind one or several functions to a signal name.
+	-- @tparam string name the name of the signal
+	-- @tparam function fn the function to unbind to the signal
+	-- @tparam function,... ... other function to unbind to the signal
 	unbind = :(name, fn, ...)
 		if not @signals[name] then
 			return
@@ -33,16 +43,20 @@ let registry_mt = {
 			end
 		end
 		if ... then
-			return @unbind(name, ...)
+			@unbind(name, ...)
 		end
 	end,
 
 	--- Remove every bound function to a signal name.
+	-- @tparam string name the name of the signal
 	unbindAll = :(name)
 		@signals[name] = nil
 	end,
 
 	--- Replace a bound function with another function.
+	-- @tparam string name the name of the signal
+	-- @tparam function sourceFn the function currently bound to the signal
+	-- @tparam function destFn the function that will replace the previous one
 	replace = :(name, sourceFn, destFn)
 		if not @signals[name] then
 			@signals[name] = {}
@@ -61,6 +75,8 @@ let registry_mt = {
 	end,
 
 	--- Emit a signal, i.e. call every function bound to it, with the given arguments.
+	-- @tparam string name the name of the signal
+	-- @param ... arguments to pass to the functions bound to this signal
 	emit = :(name, ...)
 		if @signals[name] then
 			for _, fn in ipairs(@signals[name]) do
@@ -105,7 +121,7 @@ let signal = {
 		return registry_mt.emit(signal, ...)
 	end,
 
-	--- SignalRegistry which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry
+	--- `SignalRegistry` which will be used to bind signals that need to be called on game engine event; other ubiquitousse modules may bind to this registry
 	-- if avaible.
 	--
 	-- For example, every ubiquitousse module with a "update" function will bind it to the "update" signal in the registry;
@@ -116,6 +132,7 @@ let signal = {
 	-- * `update(dt)`, should be called on every game update
 	-- * `draw()`, should be called on every game draw
 	-- * for LÖVE, there are callbacks for every LÖVE callback function that need to be called on their corresponding LÖVE callback
+	-- @ftype SignalRegistry
 	event = nil,
 
 	--- Call this function to hook `signal.event` signals to LÖVE events.
diff --git a/timer/README.md b/timer/README.md
index 68875f2..fd9201a 100644
--- a/timer/README.md
+++ b/timer/README.md
@@ -1,6 +1,6 @@
 # ubiquitousse.timer
 
-Timer and time related functions.
+Timer management for Lua.
 
 You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/timer.html).
 
diff --git a/timer/timer.lua b/timer/timer.lua
index 6c7b7e3..5d8b310 100644
--- a/timer/timer.lua
+++ b/timer/timer.lua
@@ -1,7 +1,9 @@
---- Time related functions.
+--- Timer management for Lua.
 --
 -- No dependency.
 -- @module timer
+-- @usage
+-- TODO
 local ease = require((...):match("^.-timer")..".easing")
 
 local timer_module
@@ -33,24 +35,32 @@ local timer_mt = {
 
 	--- Wait time seconds before running the function.
 	-- Specify no time to remove condition.
+	-- @tparam[opt] number time duration to wait
+	-- @treturn Timer the same timer, for chaining method calls
 	after = function(self, time)
 		self.t.after = time
 		return self
 	end,
 	--- Run the function every time millisecond.
 	-- Specify no time to remove condition.
+	-- @tparam[opt] number time duration between execution
+	-- @treturn Timer the same timer, for chaining method calls
 	every = function(self, time)
 		self.t.every = time
 		return self
 	end,
 	--- The function will not execute more than count times.
 	-- Specify no time to remove condition.
+	-- @tparam[opt] number count number of times
+	-- @treturn Timer the same timer, for chaining method calls
 	times = function(self, count)
 		self.t.times = count or -1
 		return self
 	end,
 	--- The timer will be active for a time duration.
 	-- Specify no time to remove condition.
+	-- @tparam[opt] number time duration of execution
+	-- @treturn Timer the same timer, for chaining method calls
 	during = function(self, time)
 		self.t.during = time
 		return self
@@ -62,12 +72,16 @@ local timer_mt = {
 	--- Starts the function execution when func() returns true. Checked before the "after" condition,
 	-- meaning the "after" countdown starts when func() returns true.
 	-- If multiple init functions are added, init will trigger only when all of them returns true.
+	-- @tparam function func function that returns true if condition is verified
+	-- @treturn Timer the same timer, for chaining method calls
 	initWhen = function(self, func)
 		table.insert(self.t.initWhen, func)
 		return self
 	end,
 	--- Starts the function execution when func() returns true. Checked after the "after" condition.
 	-- If multiple start functions are added, start will trigger only when all of them returns true.
+	-- @tparam function func function that returns true if condition is verified
+	-- @treturn Timer the same timer, for chaining method calls
 	startWhen = function(self, func)
 		table.insert(self.t.startWhen, func)
 		return self
@@ -75,12 +89,16 @@ local timer_mt = {
 	--- When the functions ends, the execution won't stop and will repeat as long as func() returns true.
 	-- Will cancel timed repeat conditions if false but needs other timed repeat conditions to be true to create a new repeat.
 	-- If multiple repeat functions are added, a repeat will trigger only when all of them returns true.
+	-- @tparam function func function that returns true if condition is verified
+	-- @treturn Timer the same timer, for chaining method calls
 	repeatWhile = function(self, func)
 		table.insert(self.t.repeatWhile, func)
 		return self
 	end,
 	--- Stops the function execution when func() returns true. Checked before all timed conditions.
 	-- If multiple stop functions are added, stop will trigger only when all of them returns true.
+	-- @tparam function func function that returns true if condition is verified
+	-- @treturn Timer the same timer, for chaining method calls
 	stopWhen = function(self, func)
 		table.insert(self.t.stopWhen, func)
 		return self
@@ -90,39 +108,51 @@ local timer_mt = {
 	-- @doc conditionoverride
 
 	--- Force the function to start its execution.
+	-- @treturn Timer the same timer, for chaining method calls
 	start = function(self)
 		self.t.forceStart = true
 		return self
 	end,
 	--- Force the function to stop its execution.
+	-- @treturn Timer the same timer, for chaining method calls
 	stop = function(self)
 		self.t.forceStop = true
 		return self
 	end,
 	--- Force the function to stop immediately. Won't trigger onEnd or other callbacks.
+	-- @treturn Timer the same timer, for chaining method calls
 	abort = function(self)
 		self.t.abort = true
 		return self
 	end,
 	--- Skip some amount of time.
+	-- @tparam number time duration to skip
+	-- @treturn Timer the same timer, for chaining method calls
 	skip = function(self, time)
 		self.t.skip = (self.t.skip or 0) + time
+		return self
 	end,
 
 	--- Callbacks functions
 	-- @doc callbacks
 
 	--- Add a function to the start callback: will execute func(self, lag) when the function execution start.
+	-- @tparam function func function to call when timer start
+	-- @treturn Timer the same timer, for chaining method calls
 	onStart = function(self, func)
 		table.insert(self.t.onStart, func)
 		return self
 	end,
 	--- Add a function to the update callback: will execute func(self, lag) each frame the main function is run.
+	-- @tparam function func function to call at each timer update
+	-- @treturn Timer the same timer, for chaining method calls
 	onUpdate = function(self, func)
 		table.insert(self.t.onUpdate, func)
 		return self
 	end,
 	--- Add a function to the end callback: will execute func(self, lag) when the function execution end.
+	-- @tparam function func function to call when timer ends
+	-- @treturn Timer the same timer, for chaining method calls
 	onEnd = function(self, func)
 		table.insert(self.t.onEnd, func)
 		return self
@@ -133,7 +163,8 @@ local timer_mt = {
 
 	--- Creates another timer which will be replace the current one when it ends.
 	-- Returns the new timer (and not the original one!).
-	-- @treturn Timer
+	-- @tparam function func function called by the chained timer
+	-- @treturn Timer the new timer
 	chain = function(self, func)
 		local fn = timer_module.run(func)
 		self:onEnd(function(self, lag)
@@ -242,6 +273,8 @@ local registry_mt = {
 
 	--- Create a new timer and add it to the registry.
 	-- Same as timer_module.run, but add it to the registry.
+	-- @tparam function func function called by the timer
+	-- @treturn Timer the new timer
 	run = function(self, func)
 		local r = timer_module.run(func)
 		table.insert(self.timers, r)
@@ -250,6 +283,7 @@ local registry_mt = {
 
 	--- Create a new tween timer and add it to the registry.
 	-- Same as timer_module.tween, but add it to the registry.
+	-- @treturn TweenTimer the new timer
 	tween = function(self, duration, tbl, to, method)
 		local r = timer_module.tween(duration, tbl, to, method)
 		table.insert(self.timers, r)
@@ -289,7 +323,7 @@ timer_module = {
 	-- You will need to call the :update(dt) method on the timer object every frame to make it do something, or create the timer from a timer registry if you
 	-- don't want to handle your timers manually.
 	-- @tparam[opt] function func the function to schedule
-	-- @treturn Timer the object
+	-- @treturn Timer the new timer
 	run = function(func)
 		local r = setmetatable({
 			t = {
@@ -323,8 +357,6 @@ timer_module = {
 	--- Create a timer that will tween some numeric values.
 	-- You will need to call the :update(dt) method on the timer object every frame to make it do something, or create the timer from a timer registry if you
 	-- don't want to handle your timers manually.
-	--
-	--
 	-- @tparam number duration tween duration (seconds)
 	-- @tparam table tbl the table containing the values to tween
 	-- @tparam table to the new values
@@ -374,9 +406,13 @@ timer_module = {
 
 		--- Creates another tween which will be initialized when the current one ends.
 		-- If tbl_ and/or method_ are not specified, the values from the current tween will be used.
-		-- Returns the new tween.
-		-- @treturn TweenTimer
-		r.chain = function(_, duration_, tbl_, to_, method_)
+		-- Returns the new tween timer.
+		-- @tparam number duration tween duration (seconds)
+		-- @tparam table tbl the table containing the values to tween
+		-- @tparam table to the new values
+		-- @tparam[opt="linear"] string/function method tweening method (string name or the actual function(time, start, change, duration))
+		-- @treturn TweenTimer the new timer
+		function r:chain(duration_, tbl_, to_, method_)
 			if not method_ and to_ then
 				if type(to_) == "string" then
 					tbl_, to_, method_ = tbl, tbl_, to_
diff --git a/util/README.md b/util/README.md
index 76b11f8..0b583f5 100644
--- a/util/README.md
+++ b/util/README.md
@@ -1,6 +1,6 @@
 # ubiquitousse.util
 
-Various functions useful for game developement.
+Various functions useful for Lua game developement.
 
 You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/util.html).
 
diff --git a/util/util.lua b/util/util.lua
index a938b86..e611b5c 100644
--- a/util/util.lua
+++ b/util/util.lua
@@ -1,7 +1,9 @@
---- Various functions useful for game developement.
+--- Various functions useful for Lua game developement.
 --
 -- No dependency.
 -- @module util
+-- @usage
+-- TODO
 
 --- Functions
 -- @section Functions