Appearance
Roblox port
RoNet ships as a prebuilt Roblox Model, builds/RoNet.rbxm. Drag it into the Studio Explorer anywhere under ReplicatedStorage and you get the full library as ordinary ModuleScripts with the same API, same --!strict modules, nothing extra to install.
Structure
The Model inserts one ModuleScript named RoNet plus child Folders:
ReplicatedStorage/
└── RoNet (ModuleScript; the DI root)
├── core/ Util, PRNG, Tensor, Matrix, Parallel
├── nn/ Module, Inits, Linear, Activations, Norm, Dropout,
│ Embedding, RoPE, Attention, FFN, Sequential
├── models/ MLP, TransformerBlock, Transformer
├── loss/ CrossEntropy, Losses
├── optim/ AdamW, AdEMAMix, Lion, NAdamW, CautiousAdamW,
│ ScheduleFreeAdamW, SOAP, Muon, MuonAdamW
├── train/ Scheduler, EMA, Serialize, Trainer
└── data/ BPEThe root is a single ModuleScript that wires the dependency graph, so:
lua
local RoNet = require(ReplicatedStorage.RoNet)returns the full deps table (RoNet.Util, RoNet.Tensor, RoNet.MLP, RoNet.Trainer, …). Because every ModuleScript can require() in Roblox, no factory indirection is lost; all modules stay identical to the CLI source.
Usage
A minimal classifier, identical to the interpreter quick start:
lua
-- ServerScriptService/Train.lua
local RoNet = require(ReplicatedStorage.RoNet)
local model = RoNet.MLP.new("net", { 2, 12, 1 }, RoNet.PRNG.new(1), { act = "tanh" })
local opt = RoNet.AdamW.new(RoNet.Module.collectParams(model), 0.05)
local trainer = RoNet.Trainer.new({
model = model,
optimizer = opt,
lossFn = function(m, xs, ys)
local out = m:forward(xs)
return RoNet.Losses.binaryCrossEntropy(out, RoNet.Tensor.fromData(ys, { #ys, 1 }, false))
end,
X = { { 1, 1 }, { 1, 0 }, { 0, 1 }, { 0, 0 } },
Y = { 1, 0, 0, 0 },
epochs = 20,
batchSize = 4,
featureShape = { 2 },
})
trainer:fit()The autograd engine, optimizers, Trainer, serialization, and BPE tokenizer all run in the server runtime. Keep the library in ReplicatedStorage so server Scripts can train; clients can require() the same module for inference or to drive Transformer:generate().
Parallel (multi-threaded) training
RoNet.Parallel offloads the heavy ops forward, loss, backward, and scoreGenomes onto Roblox Actor sub-VMs. One mode selection governs the whole library:
lua
local Parallel = RoNet.Parallel
Parallel.setMode("auto") -- "single" | "multi" | "auto"
Parallel.setWorkers(4) -- multi-mode shards the batch across N ActorssetMode("single")runs every job in-process, sharded the same way the multi pool would shard it, so results are bit-identical to the multi path. This is the default and the only mode the CLI build can use.setMode("multi")builds an Actor pool: a Folder (RoNet_WorkerPool) plus one Script-backed Actor per worker, placed underReplicatedStorage(move it withParallel.setParent(instance)). Jobs are sent by value withActor:SendMessage; results come back over a pool-ownedBindableEvent. Requires Play mode (Actors do not run in Edit); get the mode withParallel.available().setMode("auto")resolves tomultion a Roblox runtime and falls back tosingleunder the CLI.
Attach a model to get a pooled handle:
lua
-- ServerScriptService/TrainPar.lua
local RoNet = require(ReplicatedStorage.RoNet)
local model = RoNet.MLP.new("net", { 2, 12, 1 }, RoNet.PRNG.new(1), { act = "tanh" })
local opt = RoNet.AdamW.new(RoNet.Module.collectParams(model), 0.05)
local h = RoNet.Parallel.attach(model) -- opts: { mode, workers, ... }
local loss = h:loss(rows, targets, "mse") -- rows: {{number}}, targets: flat {number} (f per row) or rows-of-{number}
h:backward(rows, targets, "mse") -- writes summed grads into `model`, so optimizer:step() works next
local scores = h:scoreGenomes(genomes, rows) -- per-genome loss on the full batch
h:shutdown() -- disconnects pool state, destroys the worker Folder- Pooled ops return the same numbers as a single full-batch call: each worker scales its shard’s loss by its row count before
backward, and the pool divides the summed gradients by the total row count. - Handle ops accept any lossName the engine does:
mse,bce,crossentropy. - The parallel path is pure compute: no
require(), no Instance mutation inside worker jobs, so shards are deterministic.
Differences from the CLI build
- The stock Luau CLI exposes the
vectorandbufferlibraries. Roblox scripts do not expose Luau'svector(onlybuffer), soTensor.matmulFastautomatically falls back to the scalarTensor.matmulkernel and returns the exact same values. Under the CLI it still uses the SIMD fast path. - Tests,
tests/, and the.tools/Luau binaries are not shipped in the Model. - Roblox supports per-module compilation hints (
--!native/--!optimize), which the CLI's-O2 --codegenflags mirror at load time.
Rebuilding the Model
builds/RoNet.rbxm is generated, not hand-assembled. build/rbxm/ is a small Rust tool (rbx-dom: rbx_dom_weak + rbx_binary) that walks the repo exactly as the Model is laid out: the root ModuleScript is RoNet.luau with each require("./dir/Mod") rewritten to require(script.dir.Mod), one Folder per source directory, and one ModuleScript per .luau (files starting with _ are skipped). To refresh the artifact after changing source:
sh
cargo run --release --manifest-path build/rbxm/Cargo.tomlIt writes builds/RoNet.rbxm (LZ4-compressed binary, the same format Studio exports). Inspect a file with cargo run --release --manifest-path build/rbxm/Cargo.toml -- dump builds/RoNet.rbxm. No Studio session is needed to rebuild the port.