Skip to content

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; 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:

Terminal window
rudder login
rudder project use "My Game"

project use writes rudder.json at the root of the repository; commit it.

Terminal window
rudder module new bonus
created the module bonus 0.1.0 in /work/my-game/bonus; rudder module test and rudder module build run in it

A 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:

FileWhat it is
manifest.jsonThe contract: version 0.1.0 and one type, State.
main.goThe player type with one counter, Clicks, and the mutation click.
main_test.goA test of click that passes.
AGENTS.mdThe rules of writing a module, for you and for your coding agent.
go.modThe Go module, requiring rudder.build/sdk.
.gitignoreKeeps the build and go.work out of git.
rudder_gen.go, rudder_gen_test.goGenerated from the manifest and the code.
Terminal window
cd bonus
rudder module test
ok bonus 0.278s

The 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.

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:query
func (player Player) State() (State, error) {
return State{
Claimed: player.Today.Get() > 0,
Days: player.Days.Get(),
}, nil
}
//rudder:mutation
func (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()
}
  • Player embeds rudder.Player: its fields are the data each player has. Today is a counter that starts from 0 every day at the day start of the project; nothing runs at midnight for it.
  • //rudder:query and //rudder:mutation make a method a function a client calls as bonus.state and bonus.claim.
  • settings, Settings and State come from the manifest. rudder module generate (or go generate) writes them into rudder_gen.go; rudder module test, build and publish run it first.
  • ErrClaimed is a module error: the call answers 422 with the code claimed, 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).

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)
}
}
Terminal window
rudder module test
ok bonus 3.075s

rudder 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.

  1. Add a currency gold on Economy → Currencies if the project has none: the reward names it, and staging refuses the module without it.

  2. Publish a dev build onto staging:

    Terminal window
    rudder module publish
    published bonus 0.1.0-dev.1 for the project
    installed into the draft
    staging is at version 1

    publish generates, builds bonus.wasm, uploads it with the built manifest and the samples to the project of rudder.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 from default. Publish again after each change: 0.1.0-dev.2, 0.1.0-dev.3.

  3. Generate the client again; it now has rudder.bonus.claim(). Try it on staging.

  4. When it is done, rudder module publish --release publishes 0.1.0 onto staging and writes rudder.lock.json. Promote that release on Develop → Releases of the Dashboard; a release with a dev build is never promoted. Raise version in manifest.json for 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.