Your first module
A module is a Go package with a manifest.json. The manifest declares the contract: the types
of arguments and results, the catalogs a designer fills and the events. The Go code declares
the data of a player as typed fields and the functions as methods. The rudder CLI creates a
module, generates its types from the manifest, tests it without a server, builds it and uploads
it.
This page builds bonus: a reward each player claims once a day, its size set in the
Dashboard.
Install the CLI
Section titled “Install the CLI”Install the CLI; it holds the module commands. It is the only tool you need: it carries the Module SDK, and the first build downloads the compiler once, checked against its checksum, into the cache of your user. You need no Go of your own.
Sign in and choose the project the module goes to, once per machine and repository:
rudder loginrudder project use "My Game"project use writes rudder.json at the root of the repository; commit it.
Create the module
Section titled “Create the module”rudder module new bonuscreated the module bonus 0.1.0 in /work/my-game/bonus; rudder module test and rudder module build run in itA module name is lowercase letters and digits, starting with a letter. module new refuses a
directory that is not empty. It writes a module that already works:
| File | What it is |
|---|---|
manifest.json | The contract: version 0.1.0 and one type, State. |
main.go | The player type with one counter, Clicks, and the mutation click. |
main_test.go | A test of click that passes. |
AGENTS.md | The rules of writing a module, for you and for your coding agent. |
go.mod | The Go module, requiring rudder.build/sdk. |
.gitignore | Keeps the build and go.work out of git. |
rudder_gen.go, rudder_gen_test.go | Generated from the manifest and the code. |
cd bonusrudder module testok bonus 0.278sThe CLI also writes go.work, which points Go and your editor at the SDK it carries, so plain
go test ./... (with rudder on your PATH), go vet and gopls work in the module as well. go mod tidy does not work in a
module yet: run your tests through rudder module test.
Make it yours
Section titled “Make it yours”Replace the click of the template with a daily bonus.
manifest.json declares a settings catalog with one row, and the result of the functions:
{ "module": "bonus", "version": "0.1.0", "title": "Daily bonus", "description": "A reward each player claims once a day.", "icon": "gift", "types": { "Settings": { "type": "object", "required": ["reward"], "properties": { "reward": {"$ref": "rudder:amount", "title": "Reward"} } }, "State": { "type": "object", "required": ["claimed", "days"], "properties": { "claimed": {"type": "boolean", "description": "The bonus of today is claimed"}, "days": {"type": "integer", "description": "The days the player claimed it"} } } }, "content": { "settings": { "row": "Settings", "single": true, "default": {"reward": {"asset": "gold", "amount": 50}} } }, "admin": { "settings": {"catalog": "settings"} }}main.go declares the data of a player and two functions:
package main
import "rudder.build/sdk/rudder"
//go:generate rudder module generate
type Player struct { rudder.Player Today rudder.Counter `rudder:"period=day"` Days rudder.Counter}
var ErrClaimed = rudder.Error("claimed", "the bonus of today is claimed")
func main() {}
//rudder:queryfunc (player Player) State() (State, error) { return State{ Claimed: player.Today.Get() > 0, Days: player.Days.Get(), }, nil}
//rudder:mutationfunc (player *Player) Claim() (State, error) { if player.Today.Get() > 0 { return State{}, ErrClaimed }
player.Today.Add(1) player.Days.Add(1) player.Wallet().Grant(settings.Get().Reward)
return player.State()}Playerembedsrudder.Player: its fields are the data each player has.Todayis a counter that starts from 0 every day at the day start of the project; nothing runs at midnight for it.//rudder:queryand//rudder:mutationmake a method a function a client calls asbonus.stateandbonus.claim.settings,SettingsandStatecome from the manifest.rudder module generate(orgo generate) writes them intorudder_gen.go;rudder module test,buildandpublishrun it first.ErrClaimedis a module error: the call answers 422 with the codeclaimed, and nothing it wrote is kept.
Removing the template’s click is fine: nothing has been published yet, so nothing relies on
it. The first rudder module publish --release writes rudder.lock.json, and from then on
removing a function is a breaking change (see Compatibility).
Test it
Section titled “Test it”Generation also writes a test client, NewGame, with a method per function. A test runs the
module in memory with a clock you move. Replace main_test.go:
package main
import ( "errors" "testing" "time"
"rudder.build/sdk/rudder")
func TestClaimOncePerDay(t *testing.T) { game := NewGame(t) settings.Put(game, Settings{ Reward: rudder.Amount{Asset: "gold", Amount: 50}, })
if _, err := game.Claim(); err != nil { t.Fatal(err) }
if _, err := game.Claim(); !errors.Is(err, ErrClaimed) { t.Fatalf("second claim: %v, want ErrClaimed", err) }
game.Advance(24 * time.Hour)
state, err := game.Claim() if err != nil { t.Fatal(err) }
if state.Days != 2 { t.Fatalf("days %d, want 2", state.Days) }
if gold := game.Player().Wallet().Balance("gold"); gold != 100 { t.Fatalf("gold %d, want 100", gold) }}rudder module testok bonus 3.075srudder module test -v -run TestClaim passes the flags to go test; --json prints the events
of go test -json. See Testing for players, events, timers and stubs.
Take it live
Section titled “Take it live”-
Add a currency
goldon Economy → Currencies if the project has none: the reward names it, and staging refuses the module without it. -
Publish a dev build onto staging:
Terminal window rudder module publishpublished bonus 0.1.0-dev.1 for the projectinstalled into the draftstaging is at version 1publishgenerates, buildsbonus.wasm, uploads it with the built manifest and the samples to the project ofrudder.json, puts it into the draft and publishes it to staging. The Settings tab of the module on Develop → Modules shows a form with the reward, filled fromdefault. Publish again after each change:0.1.0-dev.2,0.1.0-dev.3. -
Generate the client again; it now has
rudder.bonus.claim(). Try it on staging. -
When it is done,
rudder module publish --releasepublishes0.1.0onto staging and writesrudder.lock.json. Promote that release on Develop → Releases of the Dashboard; a release with a dev build is never promoted. Raiseversioninmanifest.jsonfor the next one.
- manifest.json: every field of the contract.
- Data: counters, values, sets, records, regens, sorted sets, the wallet.
- Functions: queries, mutations, errors, time and randomness.
- Calls and events: use marketplace modules from yours.