diff --git a/config.ld b/config.ld index b38d57b..bb0b77e 100644 --- a/config.ld +++ b/config.ld @@ -3,7 +3,7 @@ title = "Ubiquitousse reference" description = "Ubiquitousse game development tools" full_description = [[Set of Lua libraries to make game development easier using the [LÖVE](https://love2d.org/) game framework. -See [main module](modules/init.html) for more information, or the [GitHub page](https://github.com/Reuh/ubiquitousse) for the source. +See [main module](modules/ubiquitousse.html) for more information, or the [GitHub page](https://github.com/Reuh/ubiquitousse) for the source. ]] --package = "ubiquitousse" @@ -31,4 +31,14 @@ custom_display_name_handler = function(item, default_handler) end topics = { "README.md", "LICENSE" } -file = { "init.lua", "ldtk/ldtk.can", "ecs/ecs.can", "asset/asset.lua" } +file = { + "init.lua", + "asset/asset.lua", + "ecs/ecs.can", + -- TODO: input + "ldtk/ldtk.can", + "scene/scene.lua", + "signal/signal.can", + "timer/timer.lua", + "util/util.lua" +} diff --git a/docs/index.html b/docs/index.html index 7245e3a..7d9c4f5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -33,9 +33,13 @@

Modules

Topics

+ + + + + + + + + + +
+ + Scene.signal +
+
+ Scene-specific SignalRegistry, if uqt.signal is available. + + + + + + + + + + + +
+
+ + Scene:enter (...) [callback] +
+
+ Called when entering a scene. + + + + + + +

Parameters:

+ + + + + + +
+
+ + Scene:exit () [callback] +
+
+ Called when exiting a scene, and not expecting to come back (scene may be unloaded). + + + + + + + + + + + +
+
+ + Scene:suspend () [callback] +
+
+ Called when suspending a scene, and expecting to come back (scene won’t be unloaded). + + + + + + + + + + + +
+
+ + Scene:resume () [callback] +
+
+ Called when resuming a suspended scene (after calling suspend). + + + + + + + + + + + +
+
+ + Scene:update (dt, ...) [callback] +
+
+ Called on each update on the current scene. + + + + + + +

Parameters:

+ + + + + + +
+
+ + Scene:draw (...) [callback] +
+
+ Called on each draw on the current scene. + + + + + + +

Parameters:

+ + + + + + +
+ +

Module

+ +
+
+ + current +
+
+ The current scene object. + + + + + + + + + + + +
+
+ + timer +
+
+ Shortcut for scene.current.timer. + + + + + + + + + + + +
+
+ + signal +
+
+ Shortcut for scene.current.signal. + + + + + + + + + + + +
+
+ + stack +
+
+ The scene stack: list of scene, from the farest one to the nearest. + + + + + + + + + + + +
+
+ + prefix +
+
+ A prefix for scene modules names. + Will search in the “scene” directory by default (prefix="scene."). Redefine it to fit your own ridiculous filesystem. + + + + + + + + + + + +
+
+ + new ([name="unamed"]) +
+
+ Creates and returns a new Scene object. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + Scene + + +
+ + + + +
+
+ + switch (scenePath, ...) +
+
+ Switch to a new scene. + The new scene will be required() and the current scene will be replaced by the new one, + then the previous scene exit function will be called, then the enter callback is called on the new scence. + Then the stack is changed to replace the old scene with the new one. + + + + + + +

Parameters:

+ + + + + + +
+
+ + push (scenePath, ...) +
+
+ Push a new scene to the scene stack. + Similar to ubiquitousse.scene.switch, except suspend is called on the current scene instead of exit, + and the current scene is not replaced: when the new scene call ubiquitousse.scene.pop, the old scene + will be reused. + + + + + + +

Parameters:

+ + + + + + +
+
+ + pop () +
+
+ Pop the current scene from the scene stack. + The previous scene will be set as the current scene, then the current scene exit function will be called, + then the previous scene resume function will be called, and then the current scene will be removed from the stack. + + + + + + + + + + + +
+
+ + popAll () +
+
+ Pop all scenes. + + + + + + + + + + + +
+
+ + update (dt, ...) +
+
+ 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. + + + + + + +

Parameters:

+ + + + + + +
+
+ + draw (...) +
+
+ Draw the current scene. + Should be called every time the game is draw. If ubiquitousse.signal is available, will be bound to the “draw” signal in signal.event. + + + + + + +

Parameters:

+ + + + + + +
+
+ + + + +
+generated by LDoc 1.4.6 +Last updated 2021-12-25 20:46:24 +
+ + + diff --git a/docs/modules/signal.html b/docs/modules/signal.html new file mode 100644 index 0000000..73cd6a8 --- /dev/null +++ b/docs/modules/signal.html @@ -0,0 +1,410 @@ + + + + + Ubiquitousse reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module signal

+

Signal management.

+

No dependency.

+ + +

Module

+ + + + + + + + + + + + + +
new ()Creates and return a new SignalRegistry.
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 + if avaible.
registerEvents ()Call this function to hook signal.event signals to LÖVE events.
+

SignalRegistry objects

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SignalRegistry.signalsMap of signals to list of listeners.
SignalRegistry:bind (name, fn, ...)Bind one or several functions to a signal name.
SignalRegistry:unbind (name, fn, ...)Unbind one or several functions to a signal name.
SignalRegistry:unbindAll (name)Remove every bound function to a signal name.
SignalRegistry:replace (name, sourceFn, destFn)Replace a bound function with another function.
SignalRegistry:clear ()Remove every bound function to every signal.
SignalRegistry:emit (name, ...)Emit a signal, i.e.
+ +
+
+ + +

Module

+ +
+
+ + new () +
+
+ Creates and return a new SignalRegistry. + + + + + + + +

Returns:

+
    + + SignalRegistry + + +
+ + + + +
+
+ + 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 + if avaible.

+ +

For example, every ubiquitousse module with a “update” function will bind it to the “update” signal in the registry; + you can then call this signal on each game update to update every ubiquitousse module easily.

+ +

Provided signals:

+ +
    +
  • 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
    • +
+ + + + + + + + + + + + + +
+
+ + registerEvents () +
+
+ Call this function to hook signal.event signals to LÖVE events. + This means overriding every existing LÖVE callback. If a callback is already defined, the new one will call the old function along with the signal:emit. + +

Requires:

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

SignalRegistry objects

+ +
+ Signal registry.

+ +

A SignalRegistry is a separate ubiquitousse.signal instance: its signals will be independant from other registries. +

+
+
+ + SignalRegistry.signals +
+
+ Map of signals to list of listeners. + + + + + + + + + + + +
+
+ + SignalRegistry:bind (name, fn, ...) +
+
+ Bind one or several functions to a signal name. + + + + + + +

Parameters:

+
    +
  • name + + +
    • +
  • fn + + +
    • +
  • ... + + +
    • +
+ + + + + +
+
+ + SignalRegistry:unbind (name, fn, ...) +
+
+ Unbind one or several functions to a signal name. + + + + + + +

Parameters:

+
    +
  • name + + +
    • +
  • fn + + +
    • +
  • ... + + +
    • +
+ + + + + +
+
+ + SignalRegistry:unbindAll (name) +
+
+ Remove every bound function to a signal name. + + + + + + +

Parameters:

+
    +
  • name + + +
    • +
+ + + + + +
+
+ + SignalRegistry:replace (name, sourceFn, destFn) +
+
+ Replace a bound function with another function. + + + + + + +

Parameters:

+
    +
  • name + + +
    • +
  • sourceFn + + +
    • +
  • destFn + + +
    • +
+ + + + + +
+
+ + SignalRegistry:clear () +
+
+ Remove every bound function to every signal. + + + + + + + + + + + +
+
+ + SignalRegistry:emit (name, ...) +
+
+ Emit a signal, i.e. call every function bound to it, with the given arguments. + + + + + + +

Parameters:

+
    +
  • name + + +
    • +
  • ... + + +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.4.6 +Last updated 2021-12-25 20:46:24 +
+
+ + diff --git a/docs/modules/timer.html b/docs/modules/timer.html new file mode 100644 index 0000000..f5eba94 --- /dev/null +++ b/docs/modules/timer.html @@ -0,0 +1,1054 @@ + + + + + Ubiquitousse reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module timer

+

Time related functions.

+

No dependency.

+ + +

Module

+ + + + + + + + + + + + + +
new ()Creates and return a new timer registry.
run ([func])Create a new timer that will run a function.
tween (duration, tbl, to[, method="linear"])Create a timer that will tween some numeric values.
+

Timer objects

+ + + + + + + + + + + + + + + + + +
Timer:after (time)Wait time milliseconds before running the function.
Timer:every (time)Run the function every time millisecond.
Timer:times (count)The function will not execute more than count times.
Timer:during (time)The timer will be active for a time duration.
+

Function conditions

+ + + + + + + + + + + + + + + + + +
Timer:initWhen (func)Starts the function execution when func() returns true.
Timer:startWhen (func)Starts the function execution when func() returns true.
Timer:repeatWhile (func)When the functions ends, the execution won’t stop and will repeat as long as func() returns true.
Timer:stopWhen (func)Stops the function execution when func() returns true.
+

Conditions override

+ + + + + + + + + + + + + + + + + +
Timer:start ()Force the function to start its execution.
Timer:stop ()Force the function to stop its execution.
Timer:abort ()Force the function to stop immediately.
Timer:skip (time)Skip some amount of time.
+

Callbacks functions

+ + + + + + + + + + + + + +
Timer:onStart (func)Add a function to the start callback: will execute func(self, lag) when the function execution start.
Timer:onUpdate (func)Add a function to the update callback: will execute func(self, lag) each frame the main function is run.
Timer:onEnd (func)Add a function to the end callback: will execute func(self, lag) when the function execution end.
+

Chaining

+ + + + + +
Timer:chain (func)Creates another timer which will be replace the current one when it ends.
+

Management

+ + + + + + + + + +
Timer:update (dt)Update the timer.
Timer:dead ()Check if the timer is dead.
+

TimerRegistry objects

+ + + + + + + + + + + + + + + + + +
TimerRegistry:update (dt)Update all the timers in the registry.
TimerRegistry:run (func)Create a new timer and add it to the registry.
TimerRegistry:tween (duration, tbl, to, method)Create a new tween timer and add it to the registry.
TimerRegistry:clear ()Cancels all the running timers in this registry.
+

TweenTimer objects

+ + + + + +
r.chain (_, duration_, tbl_, to_, method_)Creates another tween which will be initialized when the current one ends.
+ +
+
+ + +

Module

+ +
+
+ + new () +
+
+ Creates and return a new timer registry. + A timer registry provides an easy way to handle your timers; it will keep track of them, + updating and removing them as needed. If you use the scene system, a scene-specific + timer registry is available at ubiquitousse.scene.current.timer. + + + + + + + +

Returns:

+
    + + TimerRegistry + + +
+ + + + +
+
+ + run ([func]) +
+
+ Create a new timer that will run a function. + The function will receive as first parameter the timer object. + As a second parameter, the function will receive the delta time (dt). + As a third parameter, the function will receive the lag time (difference between the time when the function was run and when it should have been run). + As a fourth parameter, the function will receive as first parameter the wait(time) function, which will pause the function execution for time miliseconds. + 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. + + + + + + +

Parameters:

+
    +
  • func + function + the function to schedule + (optional) +
    • +
+ +

Returns:

+
    + + Timer + the object +
+ + + + +
+
+ + tween (duration, tbl, to[, method="linear"]) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • duration + number + tween duration (miliseconds) +
    • +
  • tbl + table + the table containing the values to tween +
    • +
  • to + table + the new values +
    • +
  • method + string/function + tweening method (string name or the actual function(time, start, change, duration)) + (default "linear") +
    • +
+ +

Returns:

+
    + + TweenTimer + the object. A duration is already defined, and the :chain methods takes the same arguments as tween (and creates a tween). +
+ + + + +
+
+

Timer objects

+ +
+ Timer methods. +
+
+
+ + Timer:after (time) +
+
+ Wait time milliseconds before running the function. + Specify no time to remove condition. + + + + + + +

Parameters:

+
    +
  • time + + +
    • +
+ + + + + +
+
+ + Timer:every (time) +
+
+ Run the function every time millisecond. + Specify no time to remove condition. + + + + + + +

Parameters:

+
    +
  • time + + +
    • +
+ + + + + +
+
+ + Timer:times (count) +
+
+ The function will not execute more than count times. + Specify no time to remove condition. + + + + + + +

Parameters:

+
    +
  • count + + +
    • +
+ + + + + +
+
+ + Timer:during (time) +
+
+ The timer will be active for a time duration. + Specify no time to remove condition. + + + + + + +

Parameters:

+
    +
  • time + + +
    • +
+ + + + + +
+
+

Function conditions

+
+ + +
+
+ + + + + + + + + + + + +
+ + Timer:initWhen (func) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + Timer:startWhen (func) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + Timer:repeatWhile (func) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + Timer:stopWhen (func) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+

Conditions override

+
+ + +
+
+ + + + + + + + + + + + +
+ + Timer:start () +
+
+ Force the function to start its execution. + + + + + + + + + + + +
+
+ + Timer:stop () +
+
+ Force the function to stop its execution. + + + + + + + + + + + +
+
+ + Timer:abort () +
+
+ Force the function to stop immediately. Won’t trigger onEnd or other callbacks. + + + + + + + + + + + +
+
+ + Timer:skip (time) +
+
+ Skip some amount of time. + + + + + + +

Parameters:

+
    +
  • time + + +
    • +
+ + + + + +
+
+

Callbacks functions

+
+ + +
+
+ + + + + + + + + + + + +
+ + Timer:onStart (func) +
+
+ Add a function to the start callback: will execute func(self, lag) when the function execution start. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + Timer:onUpdate (func) +
+
+ Add a function to the update callback: will execute func(self, lag) each frame the main function is run. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + Timer:onEnd (func) +
+
+ Add a function to the end callback: will execute func(self, lag) when the function execution end. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+

Chaining

+
+ + +
+
+ + + + + + + + + + + + +
+ + Timer:chain (func) +
+
+ Creates another timer which will be replace the current one when it ends. + Returns the new timer (and not the original one!). + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ +

Returns:

+
    + + Timer + + +
+ + + + +
+
+

Management

+
+ + +
+
+ + + + + + + + + + + + +
+ + Timer:update (dt) +
+
+ Update the timer. + Should be called at every game update. + + + + + + +

Parameters:

+
    +
  • dt + number + the delta-time (time spent since last time the function was called) (miliseconds) +
    • +
+ + + + + +
+
+ + Timer:dead () +
+
+ Check if the timer is dead. + You shouldn’t need to worry about this if your timer belongs to a registry. + If you don’t use registries, you probably should purge dead timers to free up some memory (dead timers don’t do anything otherwise). + + + + + + + +

Returns:

+
    + + bool + true if the timer can be discarded, false if it’s still active. +
+ + + + +
+
+

TimerRegistry objects

+ +
+ Registry methods. +
+
+
+ + TimerRegistry:update (dt) +
+
+ Update all the timers in the registry. + Should be called at every game update; called by ubiquitousse.update. + + + + + + +

Parameters:

+
    +
  • dt + number + the delta-time (time spent since last time the function was called) (miliseconds) +
    • +
+ + + + + +
+
+ + TimerRegistry:run (func) +
+
+ Create a new timer and add it to the registry. + Same as timer_module.run, but add it to the registry. + + + + + + +

Parameters:

+
    +
  • func + + +
    • +
+ + + + + +
+
+ + TimerRegistry:tween (duration, tbl, to, method) +
+
+ Create a new tween timer and add it to the registry. + Same as timer_module.tween, but add it to the registry. + + + + + + +

Parameters:

+
    +
  • duration + + +
    • +
  • tbl + + +
    • +
  • to + + +
    • +
  • method + + +
    • +
+ + + + + +
+
+ + TimerRegistry:clear () +
+
+ Cancels all the running timers in this registry. + + + + + + + + + + + +
+
+

TweenTimer objects

+ +
+ Tween timer: inherit all fields and methods from Timer and change a few to make them easier to use in a tweening context. +
+
+
+ + r.chain (_, duration_, tbl_, to_, method_) +
+
+ 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. + + + + + + +

Parameters:

+
    +
  • _ + + +
    • +
  • duration_ + + +
    • +
  • tbl_ + + +
    • +
  • to_ + + +
    • +
  • method_ + + +
    • +
+ +

Returns:

+
    + + TweenTimer + + +
+ + + + +
+
+ + +
+
+
+generated by LDoc 1.4.6 +Last updated 2021-12-25 20:46:24 +
+
+ + diff --git a/docs/modules/ubiquitousse.html b/docs/modules/ubiquitousse.html index ad3910b..df61cc0 100644 --- a/docs/modules/ubiquitousse.html +++ b/docs/modules/ubiquitousse.html @@ -40,9 +40,13 @@

Modules

Topics

+ + + + + + + + + + +
+ + aabb (x1, y1, w1, h1, x2, y2, w2, h2) +
+
+ AABB collision check. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + true + if the objects collide, false otherwise +
+ + + + +
+ +

List operations

+
+ + +
+
+ + + + + + + + + + + + +
+ + has (t, v) +
+
+ Check if the list contains a value. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + bool + true if is in list, false otherwise +
+ + + + +
+
+ + remove (t, x[, n=#t]) +
+
+ Remove the first occurence of an element in a list. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + x the removed element +
+ + + + +
+
+ + extract (t, k[, n=#t]) +
+
+ Extract the list of elements with a specific key from a list of tables + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the extracted table +
+ + + + +
+
+ + ipairs (a, b[, ...]) +
+
+ Chainable ipairs. + Same as ipairs, but can take several tables, which will be chained, in order. + + + + + + +

Parameters:

+ + + + + + +
+
+ + each (t, fn[, n=#t]) +
+
+ Applies a function to every item in list t. + The function receive two argument: the value and then the key. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the initial list +
+ + + + +
+
+ + map (t, fn[, n=#t]) +
+
+ Applies a function to every item in list t and returns the associated new list. + The function receive two argument: the value and then the key. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the new list +
+ + + + +
+
+ + all (t, fn[, n=#t]) +
+
+ Test if all the values in the list are true. Optionnaly applies a function to get the truthness. + The function receive two argument: the value and then the key. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + boolean + result +
+ + + + +
+
+ + any (t, fn[, n=#t]) +
+
+ Test if at least one value in the list is true. Optionnaly applies a function to get the truthness. + The function receive two argument: the value and then the key. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + boolean + result +
+ + + + +
+
+

Dictionary operations

+
+ + +
+
+ + + + + + + + + + + + +
+ + invert (t) +
+
+ Returns a new table where the keys and values have been inverted. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the inverted table +
+ + + + +
+
+ + copy (t) +
+
+ Perform a deep copy of a table. + The copied table will keep the share the same metatable as the original table. + If a key is a table, it will be reused and not copied. + Note this uses pairs() to perform the copy, which will honor the __pairs methamethod if present. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the copied table +
+ + + + +
+
+ + requirer ([prefix=""]) +
+
+ Returns a table which, when indexed, will require() the module with the index as a name (and a optional prefix). + + + + + + +

Parameters:

+ + +

Returns:

+
    + + table + the requirer table +
+ + + + +
+
+

Random and UUID

+
+ + +
+
+ + + + + + + + + + + + +
+ + uuid4 () +
+
+ Generate a UUID v4. + + + + + + + +

Returns:

+
    + + string + the UUID in its canonical representation +
+ + + + +
+
+

Object grouping

+
+ + +
+
+ + + + + + + + + + + + +
+ + group (list[, n=#t[, p=nil]]) +
+
+ Groups objects in a meta-object-proxy-thingy. + Works great with Lua 5.2+. LuaJit requires to be built with Lua 5.2 compatibility enabled to support group comparaison. + + + + + + +

Parameters:

+ + +

Returns:

+
    + + Group + object +
+ + + + +
+
+ + + + +
+generated by LDoc 1.4.6 +Last updated 2021-12-25 20:46:24 +
+ + + diff --git a/docs/topics/LICENSE.html b/docs/topics/LICENSE.html index ab8362d..ebd6b5e 100644 --- a/docs/topics/LICENSE.html +++ b/docs/topics/LICENSE.html @@ -41,9 +41,13 @@

Modules

@@ -60,7 +64,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 19:17:08 +Last updated 2021-12-25 20:46:24
diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html index 044d5cd..0126ecf 100644 --- a/docs/topics/README.md.html +++ b/docs/topics/README.md.html @@ -41,9 +41,13 @@

Modules

@@ -65,7 +69,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-25 19:17:08 +Last updated 2021-12-25 20:46:24
diff --git a/ldtk/ldtk.can b/ldtk/ldtk.can index 5e15f71..a56ce30 100644 --- a/ldtk/ldtk.can +++ b/ldtk/ldtk.can @@ -7,7 +7,7 @@ -- This modules returns a single function, @{LDtk}(path). -- -- No mandatory dependency. --- Requires LÖVE `love.graphics` (drawing Image, SpriteBatch, Quad) for drawing only. +-- Optionally requires LÖVE `love.graphics` (drawing Image, SpriteBatch, Quad) for drawing only. -- -- @module ldtk -- @require love diff --git a/scene/README.md b/scene/README.md new file mode 100644 index 0000000..9048a98 --- /dev/null +++ b/scene/README.md @@ -0,0 +1,7 @@ +# ubiquitousse.scene + +Scene management library. + +You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/scene.html). + +Licensed under ISC (equivalent to MIT/Expat/Simplified BSD). diff --git a/scene/scene.lua b/scene/scene.lua index dde5c10..9ae277c 100644 --- a/scene/scene.lua +++ b/scene/scene.lua @@ -1,27 +1,68 @@ ---- ubiquitousse.scene --- Optional dependencies: ubiquitousse.timer (to provide each scene a timer registry) --- Optional dependencies: ubiquitousse.signal (to bind to update and draw signal in signal.event) -local loaded, signal = pcall(require, (...):match("^(.-)scene").."signal") -if not loaded then signal = nil end -local loaded, timer = pcall(require, (...):match("^(.-)scene").."timer") -if not loaded then timer = nil end - --- Scene management. +-- -- 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 -- make them scene-independent, for example by creating a scene-specific TimerRegistry (TimedFunctions that are keept accross -- states are generally a bad idea). Theses scene-specific states should be created and available in the table returned by -- ubiquitousse.scene.new. +-- -- The expected code-organisation is: +-- -- * each scene is in a file, identified by its module name (scenes will be loaded using require("modulename")) -- * each scene file create a new scene table using ubiquitousse.scene.new and returns it at the end of the file +-- -- Order of callbacks: +-- -- * all scene change callbacks are called after setting scene.current to the new scene but before changing scene.stack -- * all scene exit/suspend callbacks are called before scene enter/resume callbacks +-- +-- No mendatory dependency. +-- Optional dependencies: +-- +-- * ubiquitousse.timer (to provide each scene a timer registry). +-- * ubiquitousse.signal (to bind to update and draw signal in signal.event). +-- @module scene +local loaded, signal = pcall(require, (...):match("^(.-)scene").."signal") +if not loaded then signal = nil end +local loaded, timer = pcall(require, (...):match("^(.-)scene").."timer") +if not loaded then timer = nil end + +--- Scene object. +-- @type Scene +local _ = { + --- The scene name. + name = name or "unamed", + --- Scene-specific TimerRegistry, if uqt.time is available. + timer = timer and timer.new(), + --- Scene-specific SignalRegistry, if uqt.signal is available. + signal = signal and signal.new(), + --- Called when entering a scene. + -- @callback + enter = function(self, ...) end, + --- Called when exiting a scene, and not expecting to come back (scene may be unloaded). + -- @callback + exit = function(self) end, + --- Called when suspending a scene, and expecting to come back (scene won't be unloaded). + -- @callback + suspend = function(self) end, + --- Called when resuming a suspended scene (after calling suspend). + -- @callback + resume = function(self) end, + --- Called on each update on the current scene. + -- @callback + update = function(self, dt, ...) end, + --- Called on each draw on the current scene. + -- @callback + draw = function(self, ...) end +} + +--- Module. +-- @section module + local scene scene = { - --- The current scene table. + --- The current scene object. current = nil, --- Shortcut for scene.current.timer. @@ -33,26 +74,23 @@ scene = { stack = {}, --- A prefix for scene modules names. - -- Will search in the "scene" directory by default. Redefine it to fit your own ridiculous filesystem. + -- Will search in the "scene" directory by default (`prefix="scene."`). Redefine it to fit your own ridiculous filesystem. prefix = "scene.", --- Creates and returns a new Scene object. -- @tparam[opt="unamed"] string name the new scene name + -- @treturn Scene new = function(name) return { - name = name or "unamed", -- The scene name. - - timer = timer and timer.new(), -- Scene-specific TimerRegistry, if uqt.time is available. - signal = signal and signal.new(), -- Scene-specific SignalRegistry, if uqt.signal is available. - - enter = function(self, ...) end, -- Called when entering a scene. - exit = function(self) end, -- Called when exiting a scene, and not expecting to come back (scene may be unloaded). - - suspend = function(self) end, -- Called when suspending a scene, and expecting to come back (scene won't be unloaded). - resume = function(self) end, -- Called when resuming a suspended scene (after calling suspend). - - update = function(self, dt, ...) end, -- Called on each update on the current scene. - draw = function(self, ...) end -- Called on each draw on the current scene. + name = name or "unamed", + timer = timer and timer.new(), + signal = signal and signal.new(), + enter = function(self, ...) end, + exit = function(self) end, + suspend = function(self) end, + resume = function(self) end, + update = function(self, dt, ...) end, + draw = function(self, ...) end } end, diff --git a/signal/README.md b/signal/README.md new file mode 100644 index 0000000..7642e54 --- /dev/null +++ b/signal/README.md @@ -0,0 +1,7 @@ +# ubiquitousse.signal + +Signal management library. + +You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/signal.html). + +Licensed under ISC (equivalent to MIT/Expat/Simplified BSD). diff --git a/signal/signal.can b/signal/signal.can index c5e187f..bad9745 100644 --- a/signal/signal.can +++ b/signal/signal.can @@ -1,5 +1,12 @@ ---- ubiquitousse.signal +--- Signal management. +-- +-- No dependency. +-- @module signal +--- Signal registry. +-- +-- A SignalRegistry is a separate ubiquitousse.signal instance: its signals will be independant from other registries. +-- @type SignalRegistry let registry_mt = { --- Map of signals to list of listeners. signals = {}, @@ -64,14 +71,20 @@ let registry_mt = { } registry_mt.__index = registry_mt +--- Module. +-- +-- This module also acts as a global `SignalRegistry`, so you can call the `:bind`, `:emit`, etc. methods directly on the module +-- if you don't need to isolate your signals in separate registries. +-- @section module + let signal = { --- Creates and return a new SignalRegistry. - -- A SignalRegistry is a separate ubiquitousse.signal instance: its signals will be independant from other registries. + -- @treturn SignalRegistry new = () return setmetatable({ signals = {} }, registry_mt) end, - --- Global SignalRegistry. + -- Global SignalRegistry. signals = {}, bind = (...) return registry_mt.bind(signal, ...) @@ -79,6 +92,12 @@ let signal = { unbind = (...) return registry_mt.unbind(signal, ...) end, + unbindAll = (...) + return registry_mt.unbindAll(signal, ...) + end, + replace = (...) + return registry_mt.replace(signal, ...) + end, clear = (...) return registry_mt.clear(signal, ...) end, @@ -86,17 +105,21 @@ 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. + --- 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; -- you can then call this signal on each game update to update every ubiquitousse module easily. + -- -- Provided signals: - -- * update(dt), should be called on every game update - -- * draw, should be called on every game draw + -- + -- * `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 event = nil, - --- Call this function to hook signal.event signals to the current backend. - -- For LÖVE, this means overriding every existing LÖVE callback. If a callback is already defined, the new one will call the old function along with the signal:emit. + --- Call this function to hook `signal.event` signals to LÖVE events. + -- This means overriding every existing LÖVE callback. If a callback is already defined, the new one will call the old function along with the signal:emit. -- @require love registerEvents = () local callbacks = { -- everything except run, errorhandler, threaderror diff --git a/timer/README.md b/timer/README.md new file mode 100644 index 0000000..68875f2 --- /dev/null +++ b/timer/README.md @@ -0,0 +1,7 @@ +# ubiquitousse.timer + +Timer and time related functions. + +You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/timer.html). + +Licensed under ISC (equivalent to MIT/Expat/Simplified BSD). diff --git a/timer/timer.lua b/timer/timer.lua index ea3ec2a..2d305d6 100644 --- a/timer/timer.lua +++ b/timer/timer.lua @@ -1,4 +1,7 @@ ---- ubiquitousse.timer +--- Time related functions. +-- +-- No dependency. +-- @module timer local ease = require((...):match("^.-timer")..".easing") local timer_module @@ -21,9 +24,11 @@ local function all(list, default) end end --- Timer methods. +--- Timer methods. +-- @type Timer local timer_mt = { --- timer data table + -- @local t = nil, --- Wait time milliseconds before running the function. @@ -51,7 +56,9 @@ local timer_mt = { return self end, - --- Function conditions --- + --- Function conditions + -- @doc conditions + --- 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. @@ -79,7 +86,9 @@ local timer_mt = { return self end, - --- Conditions override --- + --- Conditions override + -- @doc conditionoverride + --- Force the function to start its execution. start = function(self) self.t.forceStart = true @@ -100,26 +109,31 @@ local timer_mt = { self.t.skip = (self.t.skip or 0) + time end, - --- Callbacks functions --- - --- Will execute func(self, lag) when the function execution start. + --- Callbacks functions + -- @doc callbacks + + --- Add a function to the start callback: will execute func(self, lag) when the function execution start. onStart = function(self, func) table.insert(self.t.onStart, func) return self end, - --- Will execute func(self, lag) each frame the main function is run. + --- Add a function to the update callback: will execute func(self, lag) each frame the main function is run. onUpdate = function(self, func) table.insert(self.t.onUpdate, func) return self end, - --- Will execute func(self, lag) when the function execution end. + --- Add a function to the end callback: will execute func(self, lag) when the function execution end. onEnd = function(self, func) table.insert(self.t.onEnd, func) return self end, - --- Chaining --- + --- Chaining + -- @doc chaining + --- Creates another timer which will be replace the current one when it ends. -- Returns the new timer (and not the original one!). + -- @treturn Timer chain = function(self, func) local fn = timer_module.run(func) self:onEnd(function(self, lag) @@ -129,7 +143,9 @@ local timer_mt = { return fn end, - --- Management --- + --- Management + -- @doc management + --- Update the timer. -- Should be called at every game update. -- @tparam number dt the delta-time (time spent since last time the function was called) (miliseconds) @@ -205,6 +221,7 @@ local timer_mt = { timer_mt.__index = timer_mt --- Registry methods. +-- @type TimerRegistry local registry_mt = { --- Update all the timers in the registry. -- Should be called at every game update; called by ubiquitousse.update. @@ -246,17 +263,20 @@ local registry_mt = { } registry_mt.__index = registry_mt ---- Time related functions +--- Module. +-- @section module timer_module = { --- Creates and return a new timer registry. -- A timer registry provides an easy way to handle your timers; it will keep track of them, -- updating and removing them as needed. If you use the scene system, a scene-specific -- timer registry is available at ubiquitousse.scene.current.timer. + -- @treturn TimerRegistry new = function() return setmetatable({ --- Used to store all the functions delayed with ubiquitousse.time.delay -- The default implementation use the structure { = , ...} -- This table is for internal use and shouldn't be used from an external script. + -- @local timers = {} }, registry_mt) end, @@ -269,7 +289,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 object run = function(func) local r = setmetatable({ t = { @@ -303,11 +323,13 @@ 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 (miliseconds) -- @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 timer the object. A duration is already defined, and the :chain methods takes the same arguments as tween (and creates a tween). + -- @treturn TweenTimer the object. A duration is already defined, and the :chain methods takes the same arguments as tween (and creates a tween). tween = function(duration, tbl, to, method) method = method or "linear" method = type(method) == "string" and ease[method] or method @@ -347,9 +369,13 @@ timer_module = { copy(to, tbl, from) end) + --- Tween timer: inherit all fields and methods from `Timer` and change a few to make them easier to use in a tweening context. + -- @type TweenTimer + --- 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_) if not method_ and to_ then if type(to_) == "string" then diff --git a/util/README.md b/util/README.md new file mode 100644 index 0000000..76b11f8 --- /dev/null +++ b/util/README.md @@ -0,0 +1,7 @@ +# ubiquitousse.util + +Various functions useful for game developement. + +You can read the documentation [here](https://reuh.github.io/ubiquitousse/modules/util.html). + +Licensed under ISC (equivalent to MIT/Expat/Simplified BSD). diff --git a/util/util.lua b/util/util.lua index d6bd529..a938b86 100644 --- a/util/util.lua +++ b/util/util.lua @@ -1,12 +1,15 @@ ---- ubiquitousse.util --- No dependency. - --- Various functions useful for game developement. +-- +-- No dependency. +-- @module util + +--- Functions +-- @section Functions + local util, group_mt util = { - ------------------- - --- Basic maths --- - ------------------- + --- Basic maths + -- @doc math --- AABB collision check. -- @tparam number x1 first rectangle top-left x coordinate @@ -27,9 +30,8 @@ util = { y1 + h1 >= y2 and y1 <= y2 + h2 end, - ----------------------- - --- List operations --- - ----------------------- + --- List operations + -- @doc list --- Check if the list contains a value. -- @tparam table t the list @@ -46,7 +48,7 @@ util = { -- @tparam table t the list -- @param x the element to remove -- @tparam[opt=#t] number n the number of expected elements in the list, including nil values - -- @return x + -- @return x the removed element remove = function(t, x, n) n = n or #t for i=1, n do @@ -62,7 +64,7 @@ util = { -- @tparam table t the list of tables -- @param k the chosen key -- @tparam[opt=#t] number n the number of expected elements in the list, including nil values - -- @treturn the extracted table + -- @treturn table the extracted table extract = function(t, k, n) n = n or #t local r = {} @@ -74,6 +76,9 @@ util = { --- Chainable ipairs. -- Same as ipairs, but can take several tables, which will be chained, in order. + -- @tparam table a first list to iterate over + -- @tparam table b second list to iterate over after the first one + -- @tparam[opt] table,... ... next tables to iterate over ipairs = function(a, b, ...) if b == nil then return ipairs(a) @@ -160,9 +165,8 @@ util = { return false end, - ----------------------------- - --- Dictionary operations --- - ----------------------------- + --- Dictionary operations + -- @doc dict --- Returns a new table where the keys and values have been inverted. -- @tparam table t the table @@ -196,7 +200,7 @@ util = { end, --- Returns a table which, when indexed, will require() the module with the index as a name (and a optional prefix). - -- @tparam string[opt=""] string that will prefix modules names when calling require() + -- @tparam[opt=""] string prefix that will prefix modules names when calling require() -- @treturn table the requirer table requirer = function(prefix) prefix = prefix and tostring(prefix) or "" @@ -208,9 +212,8 @@ util = { }) end, - ----------------------- - --- Random and UUID --- - ----------------------- + --- Random and UUID + -- @doc random --- Generate a UUID v4. -- @treturn string the UUID in its canonical representation @@ -220,24 +223,23 @@ util = { :gsub("x", function() return ("%x"):format(math.random(0x0, 0xf)) end) -- random hexadecimal digit end, - ----------------------- - --- Object grouping --- - ----------------------- + --- Object grouping + -- @doc grouping --- Groups objects in a meta-object-proxy-thingy. -- Works great with Lua 5.2+. LuaJit requires to be built with Lua 5.2 compatibility enabled to support group comparaison. -- @tparam table list of objects -- @tparam[opt=#t] number n the number of expected elements in the list, including nil values -- @tparam[opt=nil] table p list of parents. Used to find the first arguments of method calls. - -- @treturn group object - group = function(t, n, p) - n = n or #t - return setmetatable({ _n = n, _t = t, _p = p or false }, group_mt) + -- @treturn Group object + group = function(list, n, p) + n = n or #list + return setmetatable({ _n = n, _t = list, _p = p or false }, group_mt) end } group_mt = { - --- Everything but comparaison: returns a new group + -- Everything but comparaison: returns a new group __add = function(self, other) if getmetatable(other) == group_mt then if getmetatable(self) == group_mt then @@ -325,7 +327,7 @@ group_mt = { return util.group(util.extract(self._t, k, self._n), self._n, self._t) end, - --- Comparaison: returns true if true for every object of the group + -- Comparaison: returns true if true for every object of the group __eq = function(self, other) if getmetatable(other) == group_mt then if getmetatable(self) == group_mt then @@ -360,7 +362,7 @@ group_mt = { end end, - --- Special cases + -- Special cases __newindex = function(self, k, v) if getmetatable(v) == group_mt then -- unpack util.each(self._t, function(t, i) t[k] = v._t[i] end, self._n) @@ -378,7 +380,7 @@ group_mt = { end end, - --- Full-blown debugger + -- Full-blown debugger __tostring = function(self) return ("group{%s}"):format(table.concat(util.map(self._t, tostring, self._n), ", ")) end