docs: an onboarding guide, and the stop verb the CLI was missing - #7
Merged
Conversation
Two ways into this tool and they are not the same shape. A mod repo already has a build tool that owns the launch, so devbridge slots into a Gradle run block. A modpack has no build tool, which is why gamebridge launch exists. Everything after startup is identical, and until now nothing said so in one place. Writing it turned up a real gap: the protocol has a stop verb and the CLI had no way to send it. An unattended loop could start a game and never close one, and `cmd stop` is not a substitute - /stop is a dedicated server's console command and does not exist in singleplayer, which is the case this whole tool is for. Added as its own subcommand. The guide also corrects a mistake the docs would otherwise have taught: options belong to the tool rather than the verb, so `cmd "..." --player @s` is an unrecognized-arguments error and `--player @s cmd "..."` is right. Everything in it was checked against this machine rather than remembered, including the Trashlands pack guard it cites, which is real (tools/check_pack_deps.py, DEV_ONLY_MODS) and runs in two of that repo's workflows.
Review of this branch. The guide told readers not to reuse somebody else's port and then supplied 25580 six times, which is the exact number two projects on this machine collided on and the reason that paragraph exists. A document that demonstrates the mistake it warns about teaches the mistake. Path A now takes '<your port>', which is not a number and so fails at startup with "devbridge.port is not a number" naming the property - a better outcome than opening a socket somebody did not choose. Path B sets PORT once at the top, so the worked example stays runnable after one edit. The remaining 25580 is in the sentence describing what happened, where it belongs. Also retitles the command table. It lists CLI subcommands rather than protocol verbs, and the two differ: shot is the screenshot verb, and launch is not a verb at all because the game is not running yet.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Adds
docs/onboarding.md, and thestopsubcommand that writing it revealed was missing.Why two paths
A mod repo already has a build tool that owns the launch, so devbridge slots into a Gradle run
block and the whole thing is a
systemProperty. A modpack has no build tool, and the CurseForgeapp offers no field for a system property, which is the entire reason
gamebridge launchexists.Everything after startup is identical. Nothing said that in one place before.
The gap it found
The protocol has a
stopverb. The CLI had no way to send it, so an unattended loop could start agame and never close one.
cmd stopis not a substitute:/stopis a dedicated server's consolecommand and does not exist in singleplayer, which is the case this tool is for. Now its own
subcommand, refusing with a useful message when pointed at RCON.
The guide also corrects something the existing docs would have taught wrongly: options belong to the
tool, not the verb, so
cmd "..." --player @sis an "unrecognized arguments" error and--player @s cmd "..."is right. I wrote it the wrong way round first and only caught it by runningit.
Verified
Everything asserted in the guide was checked on this machine rather than recalled:
stopis registered, refuses without--devbridge, and routes when given one.--player @s cmd "..."parses; the form the guide previously showed does not.tools/check_pack_deps.pydefinesDEV_ONLY_MODS = ("devbridge",)and runs in two of that repo's workflows.pingfields, the::1behaviour, the console-versus-player distinction andthe launch flow were all exercised against a running game while building feat(gamebridge): launch an instance with devbridge switched on #6.
Not verified: the Path A Gradle snippet end to end in a fresh mod repo. It is the same block this
repo's README has carried since the first commit and that Recompile uses today.