Skip to content

Latest commit

 

History

History
118 lines (80 loc) · 7.28 KB

README.md

File metadata and controls

118 lines (80 loc) · 7.28 KB
Raw

Modules

Seriously, another dependency loader for Roblox? –Somebody

Modules is a simple dependency loader for the Roblox engine. It's a single ModuleScript named "Modules" which exists in ReplicatedStorage, and it is designed to replace the built-in require function.

Click here to visit the documentation site for Modules →

Download & Install

There's several ways you can get it:

Once available, insert the Model into your Roblox place, then move the root "Modules" ModuleScript into ReplicatedStorage.

All ready for blast-off? Check out the Getting Started guide →

Usage

Replace require with the value returned by the "Modules" (the root ModuleScript). It behaves exactly the same way it did before, but in addition to typical arguments types, you can provide strings:

local require = require(game:GetService("ReplicatedStorage"):WaitForChild("Modules"))

local MyClass = require("MyLibrary:MyClass")
local AnotherClass = require("MyLibrary:Something.AnotherClass")

The ModuleLoader looks for a namespace Folder named "MyLibrary" in either ReplicatedStorage or ServerScriptService (if on the server) which contains a ModuleScript named "MyClass".

Some Goodies Included

There's a few patterns that incredibly useful in most Roblox projects, so they're included as modules. They may be required by not specifying a namespace, eg require("Event"). The included modules are:

  • class: provides utility functions for working with idomatic Lua classes
  • Event: class similar to Roblox's built-in RBXScriptSignal, it allows any kind of data and has connect, fire, wait methods
  • Maid: class for deconstructing/deallocating objects; call addTask with a connection, function, Instance or other Maid to be disconnected, called or destroyed when cleanup is called
  • StateMachine: a simple implementation of a state machine pattern, event-based or subclass based
    • State: a single state in a StateMachine

Each of these modules are documented in-code using LDoc, which also appears on the documentation site.

Development of Modules

This section is for development of Modules itself, not using it to make your own stuff. To learn how to do that, check out the documentation site. The rest of this readme will only pertain to developing Modules.

Building

The Makefile contains a build target, which creates the file Modules.rbxlx.

# Build Modules.rbxlx
$ make build
# In a new place in Roblox Studio, insert this Model into ReplicatedStorage.
# Start syncing build resources using Rojo
$ rojo serve default.project.json

Using build.project.json, invoke Rojo to build Modules.rbxmx, a Roblox model file containing only the root ModuleScript (Modules). After it is built and inserted into a Roblox place, you can use the default.project.json Rojo project file to sync changes into the already-installed instance.

Documentation

To build the documentation for this project, you need Lua 5.1 and LDoc (both of these available in Lua for Windows); additionally Python 3.7 and the libraries in requirements-docs.txt, which can be installed easily using pip.

On a Debian-based operating system, like Ubuntu, you can perhaps use these shell commands to install all the required dependencies:

$ sudo apt update
# Install Lua 5.1, LuaRocks, LuaJson and LDoc
$ sudo apt install lua5.1
$ sudo apt install luarocks
$ sudo luarocks install luajson
$ sudo luarocks install ldoc
# First install Python 3.7. You may have to add the deadsnakes ppa to do this:
$ sudo apt install software-properties-common
$ sudo add-apt-repository ppa:deadsnakes/ppa
$ sudo apt install python3.7
$ sudo apt install python3.7-venv
# Now create the virtual environment, activate it, and install Python dependencies
$ python3.7 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements-docs.txt
# At this point you're good to go!
$ make docs
# Static HTML becomes available in site/

The source for Modules documentation exists right in its source code using doc comments, as well as the docs directory. To prepare this for the web, a somewhat roundabout process is taken to building the static web content. The Makefile contains a docs target, which will do the following:

  • Using LDoc (Lua 5.1), doc comment data is exported in a raw JSON format. The docs.lua script helps with this process by providing a filter function.
  • The ldoc2mkdoc Python module in this repostory converts the raw JSON to Markdown using the Jinja2 template engine.
  • This Markdown is then passed to MkDocs to build the static website source (HTML).

Testing

The Makefile contains a test target. It invokes Rojo 0.5.x with the test.project.json file to build a Roblox place file, test.rbxlx, that runs all tests in Roblox Studio.

# Build test.rbxlx
$ make test
# Start syncing test resources using Rojo
$ rojo serve test.project.json

Tests are included in ".test" modules as children of the module they contain tests for. Tests are run using the TestRunner, which is invoked by RunTests.server.lua in "ModuleTests" in ServerScriptService. The TestRunner gathers tests from every ModuleScript whose name ends with ".test". Client tests are run by RunTests.client.lua, in StarterPlayerScripts.

License

Modules is released under the MIT License, which you can read the complete text in LICENSE.txt. This means you can use this for commercial purposes, distribute it freely, modify it, and use it privately.