purpur-fantasy-stick/README.md

Fantasy Stick

Bootstrap only. Gameplay is not implemented and this JAR is not ready for deployment.

Fantasy Stick is the proposed transferable-character RPG plugin for Social Minecraft. Its approved design uses Paper character sheets, native equipment storage and a book/basic-stick/seven-ability hotbar. These are planned features, not claims about this build.

Build and verify

• Java 25 toolchain (Gradle can resolve it), Gradle wrapper 9.6.1.
• Purpur API/runtime 26.2.build.2618-stable; plugin.yml declares API 26.2.
• Node.js 20 or later and npm for the TypeScript release-tool tests.

./gradlew clean check jar
./gradlew check jar -PreleaseVersion=0.1.0

check runs Java packaging tests, TypeScript release-client/credential-helper tests, and a native compatibility test against the checksum-verified Purpur runtime. Native preparation downloads and patches the declared runtime without starting a listening server or creating a gameplay world. A clean build repeats that preparation. Dependencies and runtime downloads require network access.

Build output is build/libs/purpur-fantasy-stick-<version>.jar. Server APIs, tests, credentials, and Node tooling are not bundled in the plugin. Runtime identity is FantasyStick, entrypoint games.dmg.fantasystick.FantasyStickPlugin, data folder FantasyStick, namespace fantasystick. Bootstrap registers no commands, permissions, recipes, sessions or gameplay listeners.

CI and publication

Gitea CI verifies pushes/PRs; main pushes run semantic-release and can publish immutable versioned JARs. Source checkout is anonymous from the public repository; external action revisions are pinned to full commit SHAs. CI and actual release publication must both be verified for the exact source commit before any deployment preparation. The first source push is currently gated on approved RELEASE_TOKEN provisioning. No remote workflow has run yet.

The release credential must be a repository-write credential authorized for dmg/purpur-fantasy-stick. Provision it through the approved protected-file/stdin workflow; never paste it into chat, commit it, or supply it as a command argument.

• Git receives the credential through the restricted git-askpass.sh pipe, for HTTPS prompts on git.garvis.dev as dmg only. Recognized semantic-release token environment names are unset so they cannot become credential-bearing Git URLs. Git HTTP redirects and credential-helper storage are disabled.
• API upload uses an in-process TypeScript client, a fixed repository URL, timeouts, redirect refusal and sanitized failures. Credentials are read from the release step's environment, never arguments or generated request files.
• Publication creates a draft, uploads/checks the expected asset name and size, then publishes. Failed calls are not automatically retried, existing releases/assets are not overwritten, and raw errors/response bodies are not logged.
• A failed run may leave a tag or draft. Inspect server-side state before proposing an approved recovery; rerunning does not imply a new release and must not overwrite an immutable asset. Verify downloaded bytes/checksum and embedded JAR version separately after publication.
• Release-client tests use synthetic credentials and stubbed HTTP responses. They do not prove a real token works or a release exists.

Canonical knowledge and delivery

Stories, design, open decisions and evidence are in the private SoMC wiki project. See AGENTS.md for the shared process. Source builds do not need wiki access.

No inventory recovery guarantees, gameplay balance, multiplayer behavior, or production compatibility have been verified by this bootstrap. Production rollout and GitOps changes remain separately approved; the development cycle never pushes GitOps.