Skip to content

Petrichor.Standard#

Petrichor preloads this when the Luau VM starts. These helpers are globals, not require() modules.

load(src, chunkname?, env?)#

Compiles a string of Luau source into a callable function. It does not run the code. You get back a closure that you call yourself.

Parameter Type Description
src string Luau source code to compile
chunkname string? Name used in error messages / stack traces. Defaults to "(load)".
env table? If provided, becomes the loaded function's environment (its _G-equivalent), letting you sandbox what globals the chunk can see.

Returns the compiled function on success, or nil, errorMessage on a compile error. Check for nil, don't wrap this in pcall.

    local fn, err = load("return 1 + 1")
    if not fn then
        log(Levels.ERR, "my-mod", "compile failed: " .. err)
        return
    end
    print(fn()) --> 2

Note

Even if you're using TypeScript, load() expects Luau code as the TypeScript is Intermediately transpiled to Luau.

declare function load(src: string, chunkname?: string, env?: object): [Function, undefined] | [undefined, string]

// INCORRECT: Load called with TypeScript code; not Luau.
const [fn, err] = load("const x: number = 1 + 1; export default x")
if (!fn) {
    print("compile failed: " + err)
} else {
    print(fn())
}

// CORRECT: Load called with Luau code; not TypeScript.
const [fn, err] = load("return 1 + 1")
if (!fn) {
    print("compile failed: " + err)
} else {
    print(fn())
}

Important

Pass an env table if you want the loaded code's reads/writes of globals isolated from the rest of the VM.

newclass(name, base?)#

Simple class table with new() and optional inheritance. Luau only. TypeScript mods use mod() instead.

local Base = newclass("Base")

function Base:init(x)
    self.x = x
end

local Derived = newclass("Derived", Base)

function Derived:init(x, y)
    self.super().init(self, x)
    self.y = y
end

local obj = Derived(1, 2)

// newclass is not available in TypeScript mods. Use mod() for entry classes.
declare function mod(name: string): any

const MyMod = mod("my-mod")
MyMod.init = function () { /* ... */ }
export = MyMod

Each instance gets:

  • self.super() to call parent methods
  • self.log(level, msg) with the class name as the log tag

mod(name)#

Builds a mod class from Petrichor.Mod:

local MyMod = mod("my-mod")

function MyMod:init()
    self:before("Foo::bar", function(ctx) ... end)
end

return MyMod

declare function mod(name: string): any

const MyMod = mod("my-mod")

MyMod.init = function () {
    this.before("Foo::bar", (ctx: HookCtx) => { /* ... */ })
}

export = MyMod

Same as newclass(name, require("Petrichor.Mod")). See Script entry point.

log(level, name, msg)#

Writes through Petrichor.Log:

log(Levels.INFO, "my-mod", "ready")
log(Levels.WARN, "my-mod", "unexpected value")
log(Levels.ERR,  "my-mod", "hook failed")

import * as Log from "Petrichor.Log"

Log.info("my-mod", "ready")
Log.warn("my-mod", "unexpected value")
Log.err("my-mod", "hook failed")

Or use require("Petrichor.Log") in Luau for Log.info / Log.warn / Log.err.

Levels#

Global Value
Levels.INFO "info"
Levels.WARN "warn"
Levels.ERR "err"