Get Started

Installation & Project Structure

The runtime has no third-party dependencies. Install the Studio-ready release asset, map the source with Rojo, or use Wally after the package is published to the registry.

Project Structure

Thread/
├── src/                  -- map this as ReplicatedStorage/Packages/Thread
│   ├── init.luau        -- Wally/Rojo package root + lifecycle
│   ├── Channel.luau     -- everything networking-related (RemoteEvents/Functions)
│   ├── Promise.luau     -- async primitive used by Thread.Start()/OnStart()
│   ├── Generated/       -- generated package metadata
│   └── Util/
│       ├── Signal.luau      -- fast in-process pub/sub (no Instance overhead)
│       ├── Trove.luau       -- cleanup/janitor helper
│       ├── TableUtil.luau   -- table helper functions
│       ├── Option.luau      -- explicit nil-handling wrapper
│       ├── EnumList.luau    -- custom, comparable enums
│       ├── MathUtil.luau    -- lerp, range remapping, fuzzy equality
│       └── TimerUtil.luau   -- debounce/throttle function wrappers
├── Tests/
│   ├── TestRunner.luau   -- ~30-line assert-based test runner, no TestEZ
│   └── Thread.spec.luau  -- the actual test suite
├── generated/            -- service manifest and static client types
├── default.project.json  -- published package model
├── dev.project.json      -- local development/test place
├── integration.project.json
├── thread.config.json    -- version and generation source
├── rokit.toml
├── wally.toml
├── README.md
├── CHANGELOG.md
└── LICENSE

Installation

Roblox Studio asset (recommended)

  1. Open the Thread releases page and select v1.2.2.
  2. Download Thread.v1.2.2.rbxm from the release assets.
  3. Drag the file into Roblox Studio.
  4. Move the resulting Thread ModuleScript to ReplicatedStorage.Packages.

Thread is then available as:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Thread = require(ReplicatedStorage.Packages.Thread)
No runtime dependencies
The release asset contains the complete Thread ModuleScript and its children. No other package is required at runtime.

Rojo source mapping

If you are consuming a source checkout, map src as the Thread ModuleScript rather than mapping it directly as Packages:

"ReplicatedStorage": {
  "Packages": {
    "$className": "Folder",
    "Thread": {
      "$path": "src"
    }
  }
}

Wally (available after registry publication)

Thread includes a valid Wally manifest, but the package must exist in the official registry before this command will work. Verify that realthonik/thread lists version 1.2.2; otherwise use the Studio asset above.

Install Wally with Rokit

If wally --version already prints a version, skip this setup. Otherwise, install Rokit using the command for your platform.

Windows PowerShell:

Invoke-RestMethod https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.ps1 | Invoke-Expression

macOS or Linux:

curl -sSf https://raw.githubusercontent.com/rojo-rbx/rokit/main/scripts/install.sh | bash

Close and reopen VS Code or your terminal so it receives the updated PATH. From your game's project directory, initialize Rokit if the project does not already contain rokit.toml, then add Wally:

rokit init
rokit add UpliftGames/wally@0.3.2
wally --version

If the repository already contains rokit.toml with Wally listed under [tools], run rokit install instead of rokit init and rokit add.

Add Thread to a game

Create a Wally manifest with wally init if your game does not already have wally.toml. Add Thread to its dependencies:

[dependencies]
Thread = "realthonik/thread@1.2.2"

Run wally install from the directory containing wally.toml, then map Wally's Packages directory into ReplicatedStorage.Packages with Rojo.

"ReplicatedStorage": {
  "Packages": {
    "$path": "Packages"
  }
}

The same require(ReplicatedStorage.Packages.Thread) call shown above then works.

Publish a Thread release (maintainers only)

Publishing is separate from installing the package. From the Thread repository root, confirm thread.config.json and the generated wally.toml contain the release version, then run:

rokit install
wally manifest-to-json
wally package --list
wally login
wally publish

Complete GitHub device authorization using the realthonik account. A successful upload prints Package published successfully!. Verify the exact version on the Wally package page afterward. Wally package versions are immutable, so a correction requires a new version rather than republishing 1.2.2.

Manual installation

If you are not using Wally, preserve the package hierarchy under a ModuleScript named Thread:

ReplicatedStorage
└── Packages
    └── Thread
        ├── Channel
        ├── Promise
        ├── Generated
        └── Util
            ├── Signal
            ├── Trove
            ├── TableUtil
            ├── Option
            ├── EnumList
            ├── MathUtil
            └── TimerUtil

Where your own code goes

There is no fixed location for your own game code — Thread.Register(folder) just points at whatever folder you keep your services/controllers in. The conventional layout is:

ServerScriptService
└── Services
    ├── MoneyService.luau
    └── DataService.luau

StarterPlayer
└── StarterPlayerScripts
    └── Controllers
        └── HudController.luau