Skip to content

Latest commit

 

History

History
239 lines (202 loc) · 8.66 KB

README.md

File metadata and controls

239 lines (202 loc) · 8.66 KB

MIT Licence Open Source Love

Love2d tools 🛠

Love2d tools is inspired by batteries.lua.

Love2d tools (or love2d-tools) is a series of LOVE2D game framework utilities to make developing games with Love2d easier and faster. It can make your game developing experience a little bit better by providing useful tools that almost every game engine has, but Love2d lacks off.

It comes with OOP, Timers, a Debugging helper, etc. All modules can be seen here.

Documentation of Love2d tools can be found here.

note: Love2d tools is NOT perfect, and you should know that bugs can occur and that it is currently Work In Progress.

Disclaimer

All modules, methods, variables, etc. are subject to change. Breaking changes will try to be avoided, but, if they are necessary a backup of the current version will be made so you can download it in case you update by accident. If any pull request that makes a breaking change is merged, a release with the previous version will be added. This means that you are responsible for going to the previous version if your project breaks

If a breaking change is not fixed, the previous version is not backed up or any other issue related to breaking changes, open an issue.

Table of contents

Installation

  1. Clone the repository
git clone https://github.com/Nykenik24/love2d-tools.git

Or add it as a submodule (recommended)

git submodule add https://github.com/Nykenik24/love2d-tools.git path/to/library

You can also download the latest release, but if you want the latest modules and features, i recomend cloning or adding as a submodule. I don't make a release every time i add a module, only when i make patches or release various modules.

  1. Require the library in your main.lua or the file where you load libraries.
Tools = require("love2d-tools.lib")
-- or you can require every module individually
Class = require("love2d-tools.modules.class")
  1. Now you can use the library, all the modules are documented.
Tools = require("love2d-tools.lib")
ClassTool = Tools.class
DebugTool = Tools.debug --note that lua already has a standard debug library, so don't name the module "debug".
TimerTool = Tools.timer

MyClass = ClassTool {
    smth = "Hello World!",
    other_thing = 5
}
MyClass_obj = MyClass:new()

MyTimer = Timer(5) --5 is the duration of the timer
MyTimer:Update()

MyTimer.OnEnd = function(self) --will be called every time the timer ends
    DebugTool.Equal(MyClass_obj.other_thing, 5)
end

Modules

Here all modules are listed.

If you contribute making a module, list it here with this format:

## Made modules
- **ModuleName** (`filename`): Brief description.

Work in Progress modules

  • Stringx (string): String handling extension. Category: Lua extensions.

NOTE: Modules may be added in the future

Made modules

General utilities

  • OOP (class): Class system, has: objects (obviously), subclasses, "merging" and "cloning" classes; etc.
  • Timer (timer): Allows to create timers, has an automatic update method and an OnEnd method that you can customize.
  • Input (input): Mouse/keyboard input helper.

Event handling

  • MessageBus (messagebus): Message bus that handles publishers and suscribers. Made by zalanwastaken.
  • StateMachine (state): State machine that handles: info, an update function, etc.

Geometry and mathematics

  • Easing (easing): Easing helper to make smoother movement or ease values. Licenses of used resources in the licenses directory.
  • Vector2 (vec2): Simple vec2 system.

Lua extensions

  • Mathx (math): Useful math functions not present in lua and love2d.
  • Tablex (table): Table handling extension. Category: Lua extensions.

Development helpers

  • Logger (logger): Logging module that uses a separate thread for minimum performance impact. Made by zalanwastaken.
  • Debug (debug): Basic debug utility with assert functions.

Data managing

  • Database (database): Database-like data managing system. Made by zalanwastaken.
  • Set (set): Simple set implementation.

Considered modules

New ideas will be added here before being added to W.I.P modules.

  • Simple JSON parser

Ideas

If you have any module idea open an issue and i will try to answer and implement your idea.

Roadmap

  • Finish all currently W.I.P modules.

More information

Inspiration

Contributing

To contribute to the project, follow these steps:

  1. Fork the repository
  2. Make all the changes you consider
  3. Make a pull request

I will try to answer as fast as posible. If i don't answer, send me an email.

If the link doesn't work, my email is [email protected]

For more info, read CONTRIBUTING.md

Making modules

I'll explain to you how i make every module. This can help if you want to contribute.

1. Create the file

When creating the files i try to name them as short as possible, without using more than one word. This is because is way more easy to manage files with simple names and for you to understand what every module does looking at the file name.

2. Write the module base

Every module has this base:

local M = {}

return M

Some modules are classes, so i need to add some extra lines.

local class = require("modules.class")
local M = {}

local M_class = class(M)
return M_class

3. Make every method and variable

Now that i have the module base, i need to make every method and every variable.

local class = require("modules.class")
local M = {}
M.SomeRandomVariable = "!dlroW olleH"

function M.SomeRandomMethod(self)
    return self.SomeRandomVariable
end

local M_class = class(M)
return M_class

But, wait. If you see the modules that are classes, you will notice how they have a new() method being returned.

local function new()
    return M_class:new()
end

You can also see how some modules have variables being choosen by the user when creating a new object.

local function new(a, b)
    local obj = M_class:new()
    obj.a = a
    obj.b = b

    return obj
end

4. Documenting

Here i just use lua annotations of the default lsp (language server) to make using the modules easier and not needing former documentation in some host like readthedocs.

---@param a number Number "a"
---@param b number Number "b"
---@return number Sum
function M.Add(a, b)
    return a + b
end

To add documentation you need to make the M variable a class with annotations. If you are using a new() method, make it return the module's annotation class:

---@class Example
local M = {}
local class = require("modules.class")
local M_class = class(M)

---@return Example
local function new()
    return M_class:new()
end

5. Final steps

After finishing the module, i check that the code is correct, look for spelling errors and all of that boring crap.

Then i add it to lib.lua and README.md (README.md format)

-- lib.lua
<module_name> = require("modules.<module_name>")


And finally i just commit and push the changes to the repo.

git add . # my alias: ga .
git commit -m 'Finished module "<module_name>"' # my alias: gcmsg <message>
git push origin main # my alias: ggpush

Tests

To run tests:

  1. Replace the test_path variable with the path of the test you would like to run.
  2. Run main.lua with love.
love .

Links