@thigasdevelopment/luam 0.1.1

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@thigasdevelopment/luam",
+    "version": "0.1.1",
+    "description": "The Luam compiler for Multi Theft Auto resources.",
+    "keywords": [
+        "mta",
+        "mtasa",
+        "multi-theft-auto",
+        "lua",
+        "lua5.1",
+        "luau",
+        "compiler",
+        "transpiler",
+        "typed-lua"
+    ],
+    "homepage": "https://github.com/ThigasDevelopment/luam#readme",
+    "bugs": {
+        "url": "https://github.com/ThigasDevelopment/luam/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ThigasDevelopment/luam.git"
+    },
+    "license": "MIT",
+    "author": "Thigas",
+    "type": "module",
+    "bin": {
+        "luam": "luam.mjs"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "files": [
+        "luam.mjs",
+        "lua",
+        "template"
+    ]
+}

package/template/README.md

@@ -0,0 +1,120 @@
+# luam-resource
+
+A Luam resource scaffolded by `luam init`. Write `.luam` sources under `src`, run
+`luam build`, and MTA gets a plain Lua 5.1 resource in `build/luam-resource`.
+
+## Commands
+
+| Command | Behavior |
+| ------- | -------- |
+| `luam check` | Compiles and reports diagnostics. Writes nothing. |
+| `luam build` | Writes the resource into `build/luam-resource`. |
+| `luam ensure` | Builds, syncs into the MTA server, restarts, and watches sources. |
+
+Set `serverPath` in `luam.json` before running `luam ensure`.
+
+## Layout
+
+```
+.env                         Declares deployment keys and safe defaults
+config.lua                   Structural settings the resource owns
+assets/                      Files copied verbatim and downloaded by clients
+src/
+  shared/
+    config.luam              Constants and helpers both sides use
+    framework/               Core, Event, Listener, Command, Loader, ThreadPool
+  server/
+    main.luam                Creates the server Core and starts it
+    handlers/                One file per server listener
+    commands/                One file per server command
+  client/
+    main.luam                Creates the client Core and starts it
+    commands/                One file per client command
+```
+
+The generated resource mirrors this tree. `src/server/main.luam` becomes
+`src/server/main.lua`, and runtime helpers land in `src/<environment>/lib`, so a
+server-only helper is never downloaded by a client.
+
+## Configuration
+
+Two files hold settings, and they have different owners.
+
+`config.lua` belongs to the resource author. It is plain Lua, copied verbatim,
+listed in `meta.xml` as a shared script, and readable by clients. Anything a
+player may see belongs here.
+
+`.env` belongs to the deployment. It declares the keys and safe defaults, and it
+is the source of truth for their types: an unquoted number is a number, `true`
+and `false` are booleans, and quoting forces a string. Override values locally in
+`.env.local`, which is never committed.
+
+The first `luam build` writes `build/<resource>/.env` from those keys, leaving
+sensitive values blank, and never overwrites it again — that file belongs to the
+server administrator.
+
+Values reach Luam through `process.env`, which exists only on the server:
+
+```lua
+outputServerLog(tostring(process.env.SERVER_NAME))
+```
+
+A key that `.env` does not declare is a compile error, and `process` in a client
+or shared file is a compile error too.
+
+## Framework
+
+`Core` owns the resource lifecycle. `main.luam` creates it with the side it runs
+on and calls `start()` once the resource has finished loading. `start()` scans
+the class registry, instantiates every `Listener` and `Command` subclass with the
+`Core` instance, and registers them.
+
+### Listeners
+
+A listener declares the MTA event it handles and overrides `handle`. Nothing
+registers it by hand — being a `Listener` subclass is enough.
+
+```lua
+class PlayerQuitListener extends Listener {
+    event: string = 'onPlayerQuit'
+
+    handle(...): void {
+        outputDebugString(getPlayerName(source) .. ' left.')
+    }
+}
+```
+
+`element` defaults to `root`. Set it to narrow the handler to one element.
+
+### Commands
+
+A command declares its name, optional aliases, and overrides `execute`. Every
+name and alias is registered.
+
+```lua
+class KickCommand extends Command {
+    name: string = 'kick'
+    aliases: string[] = { 'k' }
+    description: string = 'Kicks a player by name.'
+
+    execute(player: any, ...): void {
+        local args: any = { ... }
+
+        kickPlayer(getPlayerFromName(args[1]), player, 'kicked')
+    }
+}
+```
+
+On the server `execute` receives the calling player; on the client the first
+parameter is `nil`.
+
+### Threads
+
+`ThreadPool` wraps the `threads.lua` runtime helper, which is opt-in. Add it to
+`luam.json` before using the class:
+
+```json
+{
+    "helpers": ["threads"]
+}
+```

package/template/config.lua

@@ -0,0 +1,14 @@
+Config = {
+    greeting = 'Welcome to the server.',
+
+    spawn = {
+        x = 1959.55,
+        y = -1714.46,
+        z = 10.0,
+    },
+
+    ping = {
+        limit = 250,
+        warnAt = 180,
+    },
+}

package/template/env

@@ -0,0 +1,11 @@
+# Deployment values. This file is versioned and declares the keys and safe
+# defaults. Types come from this file: an unquoted number is a number, "true"
+# and "false" are booleans, and quoting forces a string.
+#
+# Override values on your machine in ".env.local", which is never committed.
+# The server administrator edits the generated "build/.env" instead.
+
+# Server
+SERVER_NAME="Luam Server"
+MAX_PLAYERS=32
+DEBUG=false

package/template/framework/bootstrap-client.luam

@@ -0,0 +1,9 @@
+local core: Core = new Core('client')
+
+addEventHandler('onClientResourceStart', resourceRoot, function()
+    core:start()
+end)
+
+addEventHandler('onClientResourceStop', resourceRoot, function()
+    core:stop()
+end)

package/template/framework/bootstrap-server.luam

@@ -0,0 +1,9 @@
+local core: Core = new Core('server')
+
+addEventHandler('onResourceStart', resourceRoot, function()
+    core:start()
+end)
+
+addEventHandler('onResourceStop', resourceRoot, function()
+    core:stop()
+end)

package/template/framework/command.luam

@@ -0,0 +1,54 @@
+class Command {
+    core: any = nil
+    name: string = ''
+    aliases: string[] = {}
+    description: string = ''
+
+    constructor(core: any) {
+        self.core = core
+    }
+
+    execute(player: any, ...): void {
+    }
+
+    names(): string[] {
+        local found: string[] = {}
+
+        if self.name ~= '' then
+            table.insert(found, self.name)
+        end
+
+        for index = 1, #self.aliases do
+            table.insert(found, self.aliases[index])
+        end
+
+        return found
+    }
+
+    handler(): any {
+        local command: Command = self
+
+        if self.core:isServer() then
+            return function(player: any, invoked: string, ...)
+                command:execute(player, ...)
+            end
+        end
+
+        return function(invoked: string, ...)
+            command:execute(nil, ...)
+        end
+    }
+
+    register(): number {
+        local registered: number = 0
+        local found: string[] = self:names()
+
+        for index = 1, #found do
+            addCommandHandler(found[index], self:handler())
+
+            registered += 1
+        end
+
+        return registered
+    }
+}

package/template/framework/core.luam

@@ -0,0 +1,58 @@
+class Core {
+    side: string = 'shared'
+    listeners: any = nil
+    commands: any = nil
+    started: boolean = false
+
+    constructor(side: string) {
+        self.side = side
+        self.listeners = {}
+        self.commands = {}
+        self.started = false
+    }
+
+    isServer(): boolean {
+        return self.side == 'server'
+    }
+
+    isClient(): boolean {
+        return self.side == 'client'
+    }
+
+    log(message: string): void {
+        outputDebugString('[' .. self.side .. '] ' .. message)
+    }
+
+    start(): boolean {
+        if self.started then
+            return false
+        end
+
+        self.started = true
+
+        local loader: Loader = new Loader(self)
+
+        self.listeners = loader:loadListeners()
+        self.commands = loader:loadCommands()
+
+        self:log('loaded ' .. #self.listeners .. ' listener(s) and ' .. #self.commands .. ' command(s)')
+
+        return true
+    }
+
+    stop(): boolean {
+        if not self.started then
+            return false
+        end
+
+        for index = 1, #self.listeners do
+            self.listeners[index]:unregister()
+        end
+
+        self.listeners = {}
+        self.commands = {}
+        self.started = false
+
+        return true
+    }
+}

package/template/framework/event.luam

@@ -0,0 +1,39 @@
+class Event {
+    name: string = ''
+    element: any = nil
+    handler: any = nil
+    attached: boolean = false
+
+    constructor(name: string, element: any, handler: any) {
+        self.name = name
+        self.element = element
+        self.handler = handler
+        self.attached = false
+    }
+
+    attach(): boolean {
+        if self.attached then
+            return false
+        end
+
+        self.attached = addEventHandler(self.name, self.element, self.handler)
+
+        return self.attached
+    }
+
+    detach(): boolean {
+        if not self.attached then
+            return false
+        end
+
+        removeEventHandler(self.name, self.element, self.handler)
+
+        self.attached = false
+
+        return true
+    }
+
+    describe(): string {
+        return self.name
+    }
+}

package/template/framework/listener.luam

@@ -0,0 +1,40 @@
+class Listener {
+    core: any = nil
+    event: string = ''
+    element: any = nil
+    binding: any = nil
+
+    constructor(core: any) {
+        self.core = core
+        self.binding = nil
+    }
+
+    target(): any {
+        if self.element == nil then
+            return root
+        end
+
+        return self.element
+    }
+
+    handle(...): void {
+    }
+
+    register(): boolean {
+        if self.event == '' then
+            return false
+        end
+
+        self.binding = new Event(self.event, self:target(), bind(self.handle, self))
+
+        return self.binding:attach()
+    }
+
+    unregister(): boolean {
+        if self.binding == nil then
+            return false
+        end
+
+        return self.binding:detach()
+    }
+}

package/template/framework/loader.luam

@@ -0,0 +1,73 @@
+class Loader {
+    core: any = nil
+
+    constructor(core: any) {
+        self.core = core
+    }
+
+    inherits(definition: any, baseName: string): boolean {
+        local current: any = definition
+
+        while current ~= nil do
+            local parent: any = rawget(current, '__super')
+
+            if parent == nil then
+                return false
+            end
+
+            if rawget(parent, '__name') == baseName then
+                return true
+            end
+
+            current = parent
+        end
+
+        return false
+    }
+
+    subclasses(baseName: string): string[] {
+        local found: string[] = {}
+        local definitions: table = getClasses()
+
+        for name, definition in pairs(definitions) do
+            if self:inherits(definition, baseName) then
+                table.insert(found, name)
+            end
+        end
+
+        table.sort(found)
+
+        return found
+    }
+
+    instantiate(baseName: string): any {
+        local created: any = {}
+        local names: string[] = self:subclasses(baseName)
+
+        for index = 1, #names do
+            table.insert(created, new(names[index])(self.core))
+        end
+
+        return created
+    }
+
+    loadListeners(): any {
+        local listeners: any = self:instantiate('Listener')
+
+        for index = 1, #listeners do
+            listeners[index]:register()
+        end
+
+        return listeners
+    }
+
+    loadCommands(): any {
+        local commands: any = self:instantiate('Command')
+
+        for index = 1, #commands do
+            commands[index]:register()
+        end
+
+        return commands
+    }
+}

package/template/framework/thread-pool.luam

@@ -0,0 +1,27 @@
+class ThreadPool {
+    pool: any = nil
+
+    constructor(style: string, priority: string) {
+        self.pool = Threads.new(style, priority)
+    }
+
+    add(task: any): number {
+        return self.pool:add(task, {})
+    }
+
+    remove(id: number): boolean {
+        return self.pool:remove(id)
+    }
+
+    clear(): boolean {
+        return self.pool:clear()
+    }
+
+    priority(): string {
+        return self.pool:getPriority()
+    }
+
+    setPriority(priority: string): boolean {
+        return self.pool:setPriority(priority)
+    }
+}

package/template/gitignore

@@ -0,0 +1,7 @@
+build/
+node_modules/
+.luam/
+
+.env.local
+
+*.log

package/template/luam.json

@@ -0,0 +1,11 @@
+{
+    "name": "luam-resource",
+    "version": "1.0.0",
+    "description": "A Luam resource scaffolded by luam init.",
+    "sourceDirs": ["src"],
+    "assetDirs": ["assets"],
+    "outDir": "build",
+    "transport": {
+        "kind": "none"
+    }
+}

package/template/src/client/commands/ping-command.luam

@@ -0,0 +1,8 @@
+class PingCommand extends Command {
+    name: string = 'ping'
+    description: string = 'Writes a pong line into the debug console.'
+
+    execute(player: any, ...): void {
+        outputDebugString(formatPlayerLabel('pong'))
+    }
+}

package/template/src/client/main.luam

@@ -0,0 +1,5 @@
+local core: Core = new Core('client')
+
+addEventHandler('onClientResourceStart', resourceRoot, function()
+    core:start()
+end)

package/template/src/server/commands/hello-command.luam

@@ -0,0 +1,9 @@
+class HelloCommand extends Command {
+    name: string = 'hello'
+    aliases: string[] = { 'hi', 'greet' }
+    description: string = 'Greets the calling player with the configured message.'
+
+    execute(player: any, ...): void {
+        outputChatBox(formatPlayerLabel(tostring(Config.greeting)), player)
+    }
+}

package/template/src/server/handlers/player-join-listener.luam

@@ -0,0 +1,9 @@
+class PlayerJoinListener extends Listener {
+    event: string = 'onPlayerJoin'
+
+    handle(...): void {
+        local player: any = source
+
+        outputChatBox(formatPlayerLabel(getPlayerName(player)) .. ' joined the server.', root)
+    }
+}

package/template/src/server/main.luam

@@ -0,0 +1,11 @@
+local core: Core = new Core('server')
+
+addEventHandler('onResourceStart', resourceRoot, function()
+    core:start()
+
+    outputServerLog(`[${process.env.SERVER_NAME}] started with room for ${process.env.MAX_PLAYERS} players.`)
+end)
+
+addEventHandler('onResourceStop', resourceRoot, function()
+    core:stop()
+end)

package/template/src/shared/config.luam

@@ -0,0 +1,5 @@
+RESOURCE_LABEL = getResourceName(getThisResource())
+
+function formatPlayerLabel(name: string): string
+    return `[${RESOURCE_LABEL}] ${name}`
+end

package/template/src/shared/framework/command.luam

@@ -0,0 +1,54 @@
+class Command {
+    core: any = nil
+    name: string = ''
+    aliases: string[] = {}
+    description: string = ''
+
+    constructor(core: any) {
+        self.core = core
+    }
+
+    execute(player: any, ...): void {
+    }
+
+    names(): string[] {
+        local found: string[] = {}
+
+        if self.name ~= '' then
+            table.insert(found, self.name)
+        end
+
+        for index = 1, #self.aliases do
+            table.insert(found, self.aliases[index])
+        end
+
+        return found
+    }
+
+    handler(): any {
+        local command: Command = self
+
+        if self.core:isServer() then
+            return function(player: any, invoked: string, ...)
+                command:execute(player, ...)
+            end
+        end
+
+        return function(invoked: string, ...)
+            command:execute(nil, ...)
+        end
+    }
+
+    register(): number {
+        local registered: number = 0
+        local found: string[] = self:names()
+
+        for index = 1, #found do
+            addCommandHandler(found[index], self:handler())
+
+            registered += 1
+        end
+
+        return registered
+    }
+}

package/template/src/shared/framework/core.luam

@@ -0,0 +1,58 @@
+class Core {
+    side: string = 'shared'
+    listeners: any = nil
+    commands: any = nil
+    started: boolean = false
+
+    constructor(side: string) {
+        self.side = side
+        self.listeners = {}
+        self.commands = {}
+        self.started = false
+    }
+
+    isServer(): boolean {
+        return self.side == 'server'
+    }
+
+    isClient(): boolean {
+        return self.side == 'client'
+    }
+
+    log(message: string): void {
+        outputDebugString('[' .. self.side .. '] ' .. message)
+    }
+
+    start(): boolean {
+        if self.started then
+            return false
+        end
+
+        self.started = true
+
+        local loader: Loader = new Loader(self)
+
+        self.listeners = loader:loadListeners()
+        self.commands = loader:loadCommands()
+
+        self:log('loaded ' .. #self.listeners .. ' listener(s) and ' .. #self.commands .. ' command(s)')
+
+        return true
+    }
+
+    stop(): boolean {
+        if not self.started then
+            return false
+        end
+
+        for index = 1, #self.listeners do
+            self.listeners[index]:unregister()
+        end
+
+        self.listeners = {}
+        self.commands = {}
+        self.started = false
+
+        return true
+    }
+}