Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
bc1315e
sandbox: name the services a mod calls and answer them from fixtures
paralin Nov 11, 2026
8371bd9
wasm: answer a service call in a later frame
paralin Nov 11, 2026
3ddcc9e
wasm: let a mod's layout press back to its server
paralin Nov 11, 2026
73b5729
wasm: tell observers when a mod's running build halts
paralin Nov 11, 2026
2cfdebd
README: only the sandbox reads the services a mod names
paralin Nov 11, 2026
a0a1c9c
wasm: run a Luau and a Python mod's late service calls
paralin Nov 11, 2026
e2c3a5d
panorama: say a layout's mod attribute holds the running instance's name
paralin Nov 11, 2026
3cab789
README: describe a layout's press back to its mod
paralin Nov 11, 2026
6bc400a
Merge branch 'mod-services' into modlock-next
paralin Nov 11, 2026
d7bf162
Merge branch 'layout-presses' into modlock-next
paralin Nov 11, 2026
77d2b93
preview: run layout scripts and send their presses
paralin Nov 11, 2026
00f0d31
play: answer a project's service fixtures in the game
paralin Nov 11, 2026
a7d1dc8
panorama: embed the browser's layouts source
paralin Nov 11, 2026
423b212
Merge branch 'play-fixtures' into modlock-next
paralin Nov 11, 2026
9d086e3
play: forward the mods' services to a backend as the saved login
paralin Nov 11, 2026
1a46dc4
Merge branch 'play-forward' into modlock-next
paralin Nov 11, 2026
d715049
Merge tag v0.1.77 into modlock-next
paralin Nov 12, 2026
e10a079
persist: keep records for each player across sessions
paralin Nov 13, 2026
f3fa9f5
js: check the update reply without JSON.stringify
paralin Nov 13, 2026
5dfdc20
persist: let one host at a time open a local record store
paralin Nov 13, 2026
7225753
persist: check that a refused host is told the holder's command line
paralin Nov 13, 2026
3149e31
persist: refuse an add without an update key and a value of another kind
paralin Nov 13, 2026
aa37387
persist: name the holder by process ID and program name only
paralin Nov 13, 2026
8603313
docs: keep a persist mod's mod.json under 256 KiB
paralin Nov 13, 2026
74f4ae9
persist: change a stored value only by a field of the kind that wrote it
paralin Nov 13, 2026
dd319a3
docs: resend a persist update that took too long with its same key
paralin Nov 13, 2026
5506110
Merge tag v0.1.80 into modlock-next-r1
paralin Nov 14, 2026
c13e550
project: map the well-known protobuf types for scriptc
paralin Nov 14, 2026
f0e85ce
Merge modlock-next-r1 into persist
paralin Nov 14, 2026
5f19949
Merge branch 'master' into modlock-next-r1
paralin Nov 14, 2026
8a09905
Merge modlock-next-r1 into persist
paralin Nov 14, 2026
b367e04
tests: the Python late service call test bundles the hero table
paralin Nov 14, 2026
4923a6f
Merge modlock-next-r1 into persist-r1
paralin Nov 14, 2026
2a03d44
Merge master: the ability owner guard never withholds a held ability
paralin Nov 14, 2026
83623ab
Merge modlock-next-r1 into persist-r1
paralin Nov 14, 2026
5ca16fd
mod: read the player's slot through Slot() in the persist calls
paralin Nov 15, 2026
eabf816
Merge master: precache names and the layout library's Panorama calls
paralin Nov 15, 2026
c904216
panorama: declare DispatchEvent in the layout library's $
paralin Nov 15, 2026
b01c0da
Merge modlock-next-r1: Modlock master's precache names and layout calls
paralin Nov 15, 2026
4918dff
Merge master: the squashed modlock-next (#126)
paralin Nov 15, 2026
d6b499c
Merge master: embed the whole library source (#131)
paralin Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions check/check.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (

"github.com/paralin/modlock/boards"
"github.com/paralin/modlock/metrics"
"github.com/paralin/modlock/persist"
"github.com/paralin/modlock/sandbox"
"github.com/paralin/modlock/settings"
"github.com/paralin/modlock/src/wasm"
Expand Down Expand Up @@ -68,6 +69,9 @@ func Mod(ctx context.Context, dist fs.FS) (*wasm.Manifest, error) {
if err := boards.Validate(m); err != nil {
return nil, err
}
if err := persist.Validate(m); err != nil {
return nil, err
}

// Run a module; an interpreted mod's runtime is Modlock's own.
switch {
Expand Down
122 changes: 122 additions & 0 deletions cmd/modlock/persist.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
package main

import (
"context"
"os"
"path/filepath"
"sync"

"github.com/paralin/modlock/persist"
"github.com/paralin/modlock/project"
"github.com/paralin/modlock/src/host_app/control"
"github.com/paralin/modlock/src/wasm"
"github.com/pkg/errors"
)

// persistDir is the directory a local session keeps the records of the mod
// slug built at path in: the project's own when the build is a project's,
// otherwise one in Modlock's configuration directory. Empty keeps them for
// the session only.
func persistDir(path, slug string) string {
if fixtures := projectFixtures(path); fixtures != "" {
return filepath.Join(filepath.Dir(fixtures), persist.Dir)
}
if config := configPath("persist"); config != "" && slug != "" {
return filepath.Join(config, slug)
}
return ""
}

// localPersist answers the persist calls of a local server's mods from files
// on this computer, so a mod's records survive a restart of the session. It
// learns which player is in each slot from the host's events. Persist is
// always answered here, even when the session forwards other services: the
// host names only a slot, so a forwarded call could not say whose record it
// reaches.
type localPersist struct {
// mods are the mods that declare persist record types, by slug.
mods map[string]*persistMod
// mu guards slots.
mu sync.Mutex
// slots are the players in the server, by slot.
slots map[int32]uint64
}

// persistMod is one mod's declared record types and the store of its records.
type persistMod struct {
manifest *wasm.Manifest
store *persist.Store
}

// newLocalPersist returns the local persist service of the mods built at
// dirs, printing where each mod's records are kept.
func newLocalPersist(out *printer, dirs []string) (*localPersist, error) {
local := &localPersist{mods: map[string]*persistMod{}, slots: map[int32]uint64{}}
for _, dir := range dirs {
manifest, err := project.ReadManifest(dir)
if err != nil {
return nil, err
}
if len(manifest.GetPersist()) == 0 {
continue
}
slug := manifest.GetSlug()
records := persistDir(dir, slug)
if records == "" {
if records, err = os.MkdirTemp("", "modlock-persist-"); err != nil {
return nil, err
}
}
store, err := persist.Open(records)
if err != nil {
return nil, err
}
local.mods[slug] = &persistMod{manifest: manifest, store: store}
out.mark("·", dim, slug+": service persist: kept in "+records)
}
return local, nil
}

// declares reports whether the mod slug keeps records here.
func (l *localPersist) declares(slug string) bool {
return l.mods[slug] != nil
}

// follow notes the players who join and leave, then passes event to events.
func (l *localPersist) follow(events func(*control.HostEvent)) func(*control.HostEvent) {
return func(event *control.HostEvent) {
if joined := event.GetJoined(); joined != nil {
l.mu.Lock()
l.slots[joined.GetSlot()] = joined.GetSteamId()
l.mu.Unlock()
}
if left := event.GetLeft(); left != nil {
l.mu.Lock()
delete(l.slots, left.GetSlot())
l.mu.Unlock()
}
events(event)
}
}

// player returns the SteamID64 of the player in slot; a bot has none.
func (l *localPersist) player(slot int32) (uint64, bool) {
l.mu.Lock()
defer l.mu.Unlock()
steamID := l.slots[slot]
return steamID, steamID != 0
}

// answer answers the persist calls of the mods that keep records here and
// passes every other forwarded call to next, which may be nil.
func (l *localPersist) answer(next func(context.Context, *control.ServiceCall) ([]byte, error)) func(context.Context, *control.ServiceCall) ([]byte, error) {
return func(ctx context.Context, call *control.ServiceCall) ([]byte, error) {
if mod := l.mods[call.GetMod()]; mod != nil && call.GetService() == persist.Service {
return persist.Answer(mod.store, mod.manifest, l.player, call.GetMethod(), call.GetPayload())
}
if next == nil {
return nil, errors.New("this session forwards no services")
}
return next(ctx, call)
}
}
90 changes: 90 additions & 0 deletions cmd/modlock/persist_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
package main

import (
"context"
"os"
"path/filepath"
"strings"
"testing"

"github.com/paralin/modlock/src/host_app/control"
persistpb "github.com/paralin/modlock/src/wasm/persist"
)

// TestLocalPersist answers a game session's persist calls from the project's
// files for the player the host says is in each slot, even when the session
// forwards its other services, and keeps the records past the session.
func TestLocalPersist(t *testing.T) {
// A project declares a record type and another service.
dir := t.TempDir()
build := filepath.Join(dir, "build")
manifest := `{"slug":"prophunt","services":[{"name":"persist"},{"name":"example.drills.v1"}],` +
`"persist":[{"name":"stats","writers":"WRITERS_SERVERS","fields":{"roundsWon":{"kind":"KIND_COUNT"}}}]}`
for _, file := range []string{filepath.Join(dir, "mod.json"), filepath.Join(build, "mod.json")} {
if err := os.MkdirAll(filepath.Dir(file), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(file, []byte(manifest), 0o644); err != nil {
t.Fatal(err)
}
}

// The fixtures forward persist to this computer, the rest to the origin.
records, err := newLocalPersist(&printer{brief: true}, []string{build})
if err != nil {
t.Fatal(err)
}
path := filepath.Join(t.TempDir(), "fixtures.pb")
if _, err := writeFixtures(&printer{brief: true}, []string{build}, path, "http://127.0.0.1:9", records); err != nil {
t.Fatal(err)
}
data, _ := os.ReadFile(path)
fixtures := &control.Fixtures{}
if err := fixtures.UnmarshalVT(data); err != nil {
t.Fatal(err)
}
var targets []string
for _, forward := range fixtures.GetForwards() {
targets = append(targets, forward.GetService()+" "+forward.GetTarget())
}
if strings.Join(targets, ", ") != "persist this computer, example.drills.v1 http://127.0.0.1:9" {
t.Fatalf("forwards %v", targets)
}

// A player joins slot 2 and a bot slot 3.
events := records.follow(func(*control.HostEvent) {})
events(&control.HostEvent{Body: &control.HostEvent_Joined{Joined: &control.PlayerJoined{Slot: 2, SteamId: 76561197960265729}}})
events(&control.HostEvent{Body: &control.HostEvent_Joined{Joined: &control.PlayerJoined{Slot: 3}}})
var passed []string
answer := records.answer(func(_ context.Context, call *control.ServiceCall) ([]byte, error) {
passed = append(passed, call.GetService())
return nil, nil
})
update := func(slot int32) error {
payload, _ := (&persistpb.UpdateRequest{Player: slot, Type: "stats", UpdateKey: "round-1", Ops: []*persistpb.Op{{Field: "roundsWon", Op: &persistpb.Op_Add{Add: 1}}}}).MarshalVT()
_, err := answer(t.Context(), &control.ServiceCall{Mod: "prophunt", Service: "persist", Method: "Update", Payload: payload})
return err
}

// The player's update lands in the project's file; the bot's is refused.
if err := update(2); err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(dir, ".modlock", "persist", "76561197960265729.json")); err != nil {
t.Fatal(err)
}
if err := update(3); err == nil || !strings.Contains(err.Error(), "no player is in slot 3") {
t.Fatalf("bot: %v", err)
}

// After the player leaves, the slot is empty again.
events(&control.HostEvent{Body: &control.HostEvent_Left{Left: &control.PlayerLeft{Slot: 2}}})
if err := update(2); err == nil {
t.Fatal("a left player's slot still reaches their record")
}

// Other services go to the forwarder.
if _, err := answer(t.Context(), &control.ServiceCall{Mod: "prophunt", Service: "example.drills.v1"}); err != nil || len(passed) != 1 {
t.Fatalf("forwarded %v %v", passed, err)
}
}
24 changes: 19 additions & 5 deletions cmd/modlock/play.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (
"github.com/aperturerobotics/cli"
modcli "github.com/paralin/modlock/cli"
"github.com/paralin/modlock/js"
"github.com/paralin/modlock/persist"
"github.com/paralin/modlock/project"
modpublish "github.com/paralin/modlock/publish"
"github.com/paralin/modlock/sandbox"
Expand Down Expand Up @@ -194,6 +195,7 @@ func startSession(c *cli.Context, out *printer, mods []string, logPath string) (
},
Events: events,
Fixtures: projectFixtures,
Persist: persistDir,
}), nil
}

Expand Down Expand Up @@ -238,15 +240,23 @@ func startServer(c *cli.Context, out *printer, events func(*control.HostEvent),
}
// Hand the host the projects' service fixtures, or the services to
// forward, naming who answers each service the mods call.
// Persist is answered here from the projects' files, whatever else is
// forwarded.
forward := strings.TrimSuffix(c.String("forward-services"), "/")
fixtures, err := writeFixtures(out, mods, filepath.Join(filepath.Dir(logPath), "fixtures.pb"), forward)
records, err := newLocalPersist(out, mods)
if err != nil {
return nil, err
}
fixtures, err := writeFixtures(out, mods, filepath.Join(filepath.Dir(logPath), "fixtures.pb"), forward, records)
if err != nil {
return nil, err
}
answer, err := forwarder(forward)
if err != nil {
return nil, err
}
answer = records.answer(answer)
events = records.follow(events)
running, err := session.Start(c.Context, session.Config{
Version: Version,
Mods: mods,
Expand Down Expand Up @@ -280,10 +290,10 @@ func startServer(c *cli.Context, out *printer, events func(*control.HostEvent),

// writeFixtures writes the service fixtures of the projects whose builds are
// mods to path, as the host's --fixtures file, and prints which answers each
// service a mod names: a fixture or nobody. It returns path, or empty when no
// mod has a fixture. The host refuses to start a mod whose needed service
// nobody provides.
func writeFixtures(out *printer, mods []string, path, forward string) (string, error) {
// service a mod names: a fixture, the local persist store or nobody. It
// returns path, or empty when no mod has a fixture. The host refuses to start
// a mod whose needed service nobody provides.
func writeFixtures(out *printer, mods []string, path, forward string, records *localPersist) (string, error) {
// Read each named service's fixture from its mod's project, or forward
// every service to the origin forward names.
fixtures := &control.Fixtures{}
Expand All @@ -295,6 +305,10 @@ func writeFixtures(out *printer, mods []string, path, forward string) (string, e
slug := manifest.GetSlug()
for _, service := range manifest.GetServices() {
name := service.GetName()
if name == persist.Service && records.declares(slug) {
fixtures.Forwards = append(fixtures.Forwards, &control.Forward{Mod: slug, Service: name, Target: "this computer"})
continue
}
if forward != "" {
out.mark("·", dim, slug+": service "+name+": forwarded to "+forward)
fixtures.Forwards = append(fixtures.Forwards, &control.Forward{Mod: slug, Service: name, Target: forward})
Expand Down
6 changes: 3 additions & 3 deletions cmd/modlock/play_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ func TestWriteFixtures(t *testing.T) {
// Write the host's file, keeping what the session prints.
path := filepath.Join(t.TempDir(), "fixtures.pb")
printed, written := capture(t, func() (string, error) {
return writeFixtures(&printer{}, []string{build}, path, "")
return writeFixtures(&printer{}, []string{build}, path, "", &localPersist{})
})
if written != path {
t.Fatalf("wrote %q, want %q", written, path)
Expand Down Expand Up @@ -81,15 +81,15 @@ func TestWriteFixtures(t *testing.T) {
}

// A built mod outside a project, with no fixture, writes no file.
none, err := writeFixtures(&printer{brief: true}, []string{dir}, filepath.Join(t.TempDir(), "none.pb"), "")
none, err := writeFixtures(&printer{brief: true}, []string{dir}, filepath.Join(t.TempDir(), "none.pb"), "", &localPersist{})
if err != nil || none != "" {
t.Fatalf("a mod without fixtures wrote %q, %v", none, err)
}

// A forward origin forwards every service the mod names, fixture or not.
forwarded := filepath.Join(t.TempDir(), "forwarded.pb")
printed, _ = capture(t, func() (string, error) {
return writeFixtures(&printer{}, []string{build}, forwarded, "http://127.0.0.1:9")
return writeFixtures(&printer{}, []string{build}, forwarded, "http://127.0.0.1:9", &localPersist{})
})
data, err = os.ReadFile(forwarded)
if err != nil {
Expand Down
1 change: 1 addition & 0 deletions docs/content/guides/players.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,7 @@ Python spells each call in `snake_case`, and Go capitalizes it.
| `player.addMetric(name, value, label?)` | Add to the player's total of a metric. |
| `reportScore(player, board, value, options?)`, `reportMatch(board, places, options?)` | Report a score or a match's places to a board. |
| `readBoard(board, read?)` | Read a page of a board, such as its top five. |
| `persist.get(player, type)`, `persist.getMany(players, type)`, `persist.update(player, type, changes, options?, done?)` | Read or change the player's record of a [persist](/reference/manifest#persist) type. |
| `player.handoff(text)`, `handedOff()` | Hand the player's state to the next build, and read it back. |
| `player.watchMovement(true)` | Add the hero's movement, landings and wall jumps to each frame. |
| `playCamera(player, options)`, `cameraPulse`, `cameraShake` | Play curves on the camera, TypeScript only; see [Camera moves](/guides/camera). |
Expand Down
Loading
Loading