WIP: feat(panel): a playtest panel in the browser, with a live saved-flags editor, on the modding API #2190
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
5 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!2190
Loading…
Reference in a new issue
No description provided.
Delete branch "BeanSeller/Longshot:feat/playtest-panel"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Depends on #1958 (the modding API). As HumanBean suggested, the panel's game side is now a small mod on the modding
API, and the PR changes no host code: the bridge commands it carried before (
warp,give,spawn,enemies,edit,flagsand the rest) are gone. Its mod builds onmod_evaland the API of #1958, so it is work in progressuntil #1958 is merged.
Testing a mod or a change by hand means switching between the game and a terminal to teleport, hand out items, or
check what the game just did. This PR adds a playtest panel: a page in the browser beside the game (or on a phone
on the same network) that walks a tester through a list of steps with pass and fail buttons, goes to places, hands out
items, saves notes with Link's position and a screenshot, records short clips, and shows the saved flags live,
flipping a checkbox by itself when the game changes a flag, highlighting what just changed, and writing a flag when the
tester ticks it. Steps can carry their own set-up buttons and one-click notes. Everything is written to a session
folder as it happens (notes, screenshots, finished clips, flag changes, the current status, an access log), and a
messages file is shown at the top of the page, so a person or a program following a session can see it live and answer
the tester; the panel assumes no one in particular is watching. Project-specific cards are the user's own HTML files in
an extras folder, kept outside the repository.
Three parts, all in
scripts/playtest_panel/:mod/, the modlocal/playtest-panel: exports the panel calls (state,readFlags,setFlag,destinations,travel,moveTo,give,heal,rupees,spawn,enemies) ongame.flags,player,world,items.grantand
actors, and does nothing on its own. Flags are read by name, 400 a frame, so thousands stay inside a callback'sbudget; a flag is written through
game.flags.set(the game's own setter), which also settles the "a write inplace may not be saved" limit the earlier version had.
server.py: standard library Python on 127.0.0.1. It calls the mod's exports through the bridge'smod_eval(thegame started with
longshot mod run --eval), and uses main's own bridge commands for the rest:status,teleport,shot,press, andsubscribe(ootwithchanges) for every flag the game changes while the flagscard is open.
--game <folder>finds the running game's socket withlongshot mod attach --json.index.html: the page. Extra panels getpanel.call(export, ...args)besidepanel.bridge(cmd, args).The game keeps only the flag names' MurMur3 hashes, so names come from files the user gives (
--flag-names), and thepage can learn a name typed in its search box. A flag without a name shows by its hash when it changes, and is read
only: the API writes flags by name.
Read first:
scripts/playtest_panel/mod/src/main.ts,scripts/playtest_panel/server.py(Game.call,Flags),docs/dev/reference/playtest-panel.md.Testing
Tested: Windows 11, RTX 4070 Ti SUPER, driver 610.88.
66984acf):longshot-mod checkpasses (the manifest, oxc compile and link,tsc --noEmitwith TypeScript 7.0.2: no errors);longshot-mod lint: no problems (the permissions the code uses are the ones declared);longshot-mod testin the fake game: 1 passed, 7 skipped (the 7 call the mod's exports and are the real game's: the fake game runs tests in Node, where a module importing the API cannot load).nx2/make_game.pyand the TypeScript compiler (scripts/longshot_ts.py build); in its test mode (--mod-tests) the mod started (script runtime: started local/playtest-panel 0.1.0 (18.1 ms, 489 KB ...)), with no fault.python -I -B tests/test_playtest_panel.pypasses (10: MurMur3 against known values, the names files, themod_evalrequest a call sends and its error, flags read by name and the changessubscribereports, a dropped-changesmorereading the flags again, learning a name, writing a flag by name, going to a place (a move the game drops is asked again), buttons with calls and bridge requests,/call, step actions, the messages file, extras, the page-only header, the LAN access key, the session files and the access log).python -I -B tests/run_all.py --changed: 11 passed, 3 failed, 1 skipped; the 3 (test_dev_build,test_dev_packs,test_mise_build) fail the same way on this PC on the branch's previous tree, which shares main's files they read.Not run in the game yet, and why: on this PC, #1958's head does not reach play from a save. With no mod at all (
mods/left out), the title skip loads a save and the game stays on the loading screen (control: state menu -> loading, annn.npln.Workermutex waiting); main ata2dc538loads the same save. Building it on Windows with llvm-mingw also needed two local fixes, not in this PR (nearis a macro of windows.h ingpu/vk/vk_texture.cpp;ndefined twice inhost/modtool/modtool.c), and a confined game cannot mount its save (the sandbox does not grant<user>/save-work; withHOS_SANDBOX=0it mounts). I will report these on #1958.Still to test:
longshot mod test --gameinscripts/playtest_panel/mod(the mod's 7 game tests), then the panel withlongshot mod run --evaland--game: a flag ticked and read back, a change the game makes showing in the page, Go to, magic jars, a fairy, an item, a note, a clip (by hand).@Beanstalkonce #1958 is merged).Measurements
Nothing to measure: the mod does nothing while no call comes (one check of an empty queue in
update); areadFlagscall reads at most 400 names, and at most 2 ms, a frame.
Risks
Test tooling only, and no host code. The mod runs only where it is installed in
mods/and turned on, with thepermissions its
mod.jsonlists as the player granted them (state.read,state.write,items.grant,actors.read,actors.spawn;multiplayer: "host"); the panel reaches it only throughmod_eval, so only in devmode with
HOS_CONTROL_EVAL=1, and sends it only a call of one of its exports. The panel listens on 127.0.0.1 bydefault;
--lanopens it to the local network behind a random access key, and every POST needs a header anothersite's page cannot send. A revert is enough to take it out.
Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named). (not run again for this change: the change adds no host code; the panel and the mod are checked above.)main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
🤖 Generated with Claude Code
Tested in game: Windows 11, RTX 4070 Ti SUPER, driver 610.88: the branch built as a game folder, a save loaded (Water Temple, then Hyrule Field). longshot_ctl.py flags returned 11 292 bools and 1 259 ints in 0.3 s. In the panel: the flags card listed them with names from a names file; ticking a flag set it in the game (flag get read it back); flags changed from the command line and by the game during a teleport flipped and highlighted in the page within a second. Go to (teleport then warp, arrival checked), magic jars, fairy, full health, a note with screenshot, an 8 s clip, and the page from the PC's LAN address with the access key. This run was on the branch before its rebase onto
a2dc538; the rebased branch was built again and its checks re-run, not played.Possibly related, for context:
@Beanstalk On Linux, any GPU: build this branch as a game folder (host/control.c and host/hos_main.c changed), start it with the bridge on (HOS_CONTROL) and load a save. Then run python -I scripts/longshot_ctl.py flags, warp to a spot near Link (status's pos), spawn Obj_Fairy, and give "Kokiri Sword". Expected: the build succeeds; flags returns a bools count around 11 000 and an ints count around 1 200; Link moves to the warp position; a fairy appears in front of him; the sword is given. Please report the build log's result and each command's reply.
@BeanSeller only members of
BigBeanscan start the farm.One of them can approve this request by reacting 👍 to it or to this comment.This request was for76acc57, and the PR has changed since (18754c8), so a 👍 no longer approves it. Comment@Beanstalkagain to ask for the new commit.Hi! This would fit better for our new mod API, please try it!
Try the Longshot Modding API
The Modding API is up for testing in #1958: mods in TypeScript that the game compiles and runs in a sandbox. There's a Mods tab, hot reload, and an inspector on F8.
Build it with the launcher:
1958.Then:
mods/folder, for exampleenemy-names. Turn it on in Insert → Mods and allow its permissions.Docs, on the branch:
Please post what breaks, what's confusing, or what's missing as a comment on #1958. Include your OS and GPU, and the
logs/longshot_log.txtlines around the problem.on it. updating to use the new mod api.
WIP: feat(control): a playtest panel in the browser, a live saved-flags editor, and the bridge's test toolsto WIP: feat(panel): a playtest panel in the browser, with a live saved-flags editor, on the modding APIThanks, @HumanBean: done in
18754c87. The panel's game side is now a mod on the modding API (scripts/playtest_panel/mod: game.flags, player, world.travel, items.grant, actors), which the panel calls through the bridge's mod_eval; flag changes come from the bridge's own subscribe. The PR no longer changes any host code: the bridge commands it added are gone. It depends on #1958 and stays WIP until that is merged. The mod passes longshot-mod check and lint and starts in a build of #1958; its game tests have not run yet, because #1958's head does not reach play from a save on my Windows build (details under Testing, and I'll report them on #1958).that prev msg was my agent. I'm manually testing now and will report-back once that's done.
The panel turns the bridge's same-user-only Unix socket into a TCP HTTP surface, but the only browser guard is a custom header that is not an origin check — and
/bridgeforwards any bridge command, includingmod_evalwith arbitrary code andquit.Strongest finding:
/bridgeis an unrestricted command channel, andX-Panel: 1is not an origin check. The doc's Safety section says "another site's page ... cannot send that header without asking first, which the panel never allows, so it cannot use the panel to drive the game", and "The panel sendsmod_evalonly a call of one of the exports above." Both are stronger than the code:do_POSTchecks onlyX-Panel: 1andallowed(). With no--lan,panel.keyis None andallowed()returns True for every client. The server never checksHostorOrigin. So a DNS-rebound page is same-origin to its ownhttp://host:8765, and itsfetchwithX-Panel: 1is not a cross-origin request. I started the handler and sentPOST /bridge {"cmd":"quit"}withHost: evil.example:8765,Origin: http://evil.example:8765,X-Panel: 1, no key: 200, and the stand-in bridge received("quit", {}). Whether a given browser stops the DNS-rebinding step (Chromium's Private Network Access may) is the browser's call, not the panel's; the server has no check of its own./bridgedoesself.game.request(str(body.pop("cmd","")), **body), bypassingGame.call'sCALLSallowlist.POST /bridge {"cmd":"mod_eval","mod":"local/playtest-panel","code":"export default 1"}was forwarded verbatim. So the panel can run arbitrary code in the mod runtime, not only the exports. The test's own CSRF payload is{"cmd":"quit"}(test_a_post_without_the_panel_header_is_refused), which shows the channel's reach.control-bridge.md#securitysays the bridge is "Local and this user only ... never TCP". The panel is the TCP front-end to it, so a browser page (which cannot reach a Unix socket) now can. That is the new capability, and the doc should not claim it is closed.What it can change. Through the exports: read state/flags, write flags, travel (map change), move, give items, heal, set rupees, spawn actors. Through
/bridge: any bridge command — the control-bridge doc lists "anything the player can do with a controller and the Insert menu's settings, plus teleport and age switch, writing a PNG, listing the save folder, reading every flag, and quitting or relaunching the game." Through a step'scmds:longshot_ctl.pycommand lines. Through--extras: the page injects the extra HTML withinnerHTMLand re-runs its scripts in the panel origin, withpanel.bridge/call/post; a project's extras folder is therefore code execution, not data. So a browser client (a DNS-rebound page, an extra, or any local process) can quit/relaunch the game, teleport, press buttons, and write saved flags without the tester's click.--lan: binds0.0.0.0, answers loopback/private/link-local peers only, and requires a random 96-bit key (X-Panel-Keyor?key=). But the key is in the printed URL and is written toaccess.log:log_messagelogsself.requestline, which includes?key=.... I sentGET /state?key=s3cr3t-key; the log line was... "GET /state?key=s3cr3t-key HTTP/1.1" 200 -. The doc encourages a person or program to follow the session folder, so the key leaks to the audience it is meant to exclude. Log the path without the query, and prefer the header over the URL.Saved flags.
/flagdoesself.flags.set(name, int(value))→ the mod'ssetFlag→flags.has(name) && flags.set(name, value). The panel does no type/range check; I sent{"name":"Chest.Opened","value":7}(a 0/1 flag) and the stand-in accepted 7. The real validation is #1958'sflags.set, which is open and unmerged, and the test's fake accepts anything; the saved-flag write contract is unverified until #1958 lands. The write goes through the game's setter (the PR says it marks the save), so a client with access can change the player's saved flags.Modding API use / default off. The mod uses
flags,player,world,items.grant,actors, declaresstate.read/write,items.grant,actors.read/spawn,multiplayer: host, andlongshot-mod lintsays the permissions cover the uses; it does nothing on its own. No host code: the diff isscripts/playtest_panel/,tests/, the README and the doc only, and the mod must be installed and the game started withlongshot mod run --eval. So it is off by default; the caveat is that the default local mode has no auth.Test.
tests/test_playtest_panel.pypasses 10/10 here (I applied the PR toa2dc538and ran it). It covers theX-Panelheader (403 without), the--lankey (403 missing/wrong, 200 with), extras traversal, flags read/subscribe, buttons/actions, notes and the access log. It does not cover:Host/Origin/DNS rebinding, any restriction on/bridge, the key inaccess.log,nearby()refusing a public peer, or a flag value the game should reject. The messages, recent log and steps render astextContent(no script injection there); the extras are the deliberate exception.What remains. I could not run the in-game mod tests or the panel end to end: #1958 is open (head now
a334ed61; the author tested66984acf), and this PR is WIP/draft and not mergeable. Theflags.setvalidation contract, the mod's permissions against a real game, and the LAN path on a phone are unverified. The security items above are verifiable without the game and are what I would fix before this leaves WIP.No approval, no claim.
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.