Installation

Installation

This page installs the v0.1.0-rc.1 Runtime and TypeScript toolchain from their canonical GitHub prereleases. ShamooRuntime and ShamooTS use synchronized tags, but they are separate repositories and releases.

Exact prerequisites

Requirement	Supported value
Java	Java 21; use a Java 21-compatible Paper/Velocity host
Runtime host OS	Linux x86-64 only for the bundled Javet/Node 5.0.9 native runtime
Development Node.js	Node.js 22 or newer; CI covers Node 22 and 24
pnpm	pnpm 10 or newer; the ShamooTS repository pins pnpm 11.15.0
GitHub CLI	2.49.0 or newer for artifact attestation verification
TypeScript	5.8.3 is the pinned and tested compiler
Paper	Paper 1.21.8 build 55; API 1.21.8-R0.1-20250906.215025-55
Velocity	Velocity 3.4.0 build 566 process fixture; generated API 3.4.0-20260121.190037-118
Paper NMS/packets	Minecraft 1.21.8, Paper build 55, Mojang mappings, Mache 2

Node and pnpm are development requirements. ShamooRuntime embeds its own pinned Javet/Node runtime; do not install system Node on the Minecraft server as a substitute for the Runtime JAR.

Enable the package manager shim and verify tools:

corepack enable
node --version
pnpm --version
java -version

Install ShamooRuntime

Download all Runtime release assets, verify checksums and GitHub attestations, then install only the JAR for the target platform:

set -euo pipefail
TAG=v0.1.0-rc.1
REPO=wasmake/ShamooRuntime
DEST="$PWD/shamoo-runtime-$TAG"
mkdir "$DEST"
gh release download "$TAG" --repo "$REPO" --dir "$DEST"
(cd "$DEST" && sha256sum --check SHA256SUMS)
for artifact in "$DEST"/*.jar "$DEST"/*.spdx.json "$DEST"/SHA256SUMS; do
  gh attestation verify "$artifact" \
    --repo "$REPO" \
    --signer-workflow "$REPO/.github/workflows/release-candidate.yml" \
    --source-ref "refs/tags/$TAG"
done
for artifact in "$DEST"/*.jar; do
  gh attestation verify "$artifact" \
    --repo "$REPO" \
    --signer-workflow "$REPO/.github/workflows/release-candidate.yml" \
    --source-ref "refs/tags/$TAG" \
    --predicate-type https://spdx.dev/Document/v2.3
done

Stop the server before copying the JAR.

Paper:

install -m 0644 "$DEST/shamoo-runtime-paper-${TAG#v}.jar" /path/to/paper/plugins/

The JAR path is <paper-server>/plugins/shamoo-runtime-paper-0.1.0-rc.1.jar. Paper creates the Runtime data directory at <paper-server>/plugins/ShamooRuntime. With the shipped plugins.directory: plugins, the watched script-plugin root is exactly:

<paper-server>/plugins/ShamooRuntime/plugins

plugins.directory may be an absolute path or a path relative to the ShamooRuntime data directory. Other Paper settings are in plugins/ShamooRuntime/config.yml.

Velocity:

install -m 0644 "$DEST/shamoo-runtime-velocity-${TAG#v}.jar" /path/to/velocity/plugins/

The JAR path is <velocity-server>/plugins/shamoo-runtime-velocity-0.1.0-rc.1.jar. The plugin ID is shamooruntime, so the default data and watched paths are:

<velocity-server>/plugins/shamooruntime
<velocity-server>/plugins/shamooruntime/plugins

Override the Velocity watched root at JVM startup when needed:

java -Dshamoo.plugins.directory=/absolute/watched/root -jar velocity.jar

Paper and Velocity Runtime JARs are not interchangeable. Restart the server and confirm the log reports Runtime 0.1.0-rc.1, protocol 1.0, and the generated platform event count.

Install TypeScript release tarballs

The v0.1.0-rc.1 ShamooTS prerelease contains one .tgz for every public @shamoo/* package, shamoo-v0.1.0-rc.1.spdx.json, and SHA256SUMS. Download and verify the complete set:

set -euo pipefail
TAG=v0.1.0-rc.1
REPO=wasmake/ShamooTS
DEST="$PWD/shamoo-ts-$TAG"
mkdir "$DEST"
gh release download "$TAG" --repo "$REPO" --dir "$DEST"
(cd "$DEST" && sha256sum --check SHA256SUMS)
for artifact in "$DEST"/*.tgz "$DEST"/*.spdx.json "$DEST"/SHA256SUMS; do
  gh attestation verify "$artifact" \
    --repo "$REPO" \
    --signer-workflow "$REPO/.github/workflows/release-candidate.yml" \
    --source-ref "refs/tags/$TAG"
done
for artifact in "$DEST"/*.tgz; do
  gh attestation verify "$artifact" \
    --repo "$REPO" \
    --signer-workflow "$REPO/.github/workflows/release-candidate.yml" \
    --source-ref "refs/tags/$TAG" \
    --predicate-type https://spdx.dev/Document/v2.3
done

Install all candidate tarballs together. Their manifests use synchronized @shamoo/* ranges, so installing only one tarball can cause a package manager to query a registry for its Shamoo dependencies.

pnpm add /absolute/path/to/shamoo-ts-v0.1.0-rc.1/*.tgz

The npm equivalent is npm install /absolute/path/to/release/*.tgz. After resolution is locked, unneeded direct entries may be removed only if the package manager retains local tarball resolutions for transitive Shamoo packages.

The npm registry is not yet the canonical Shamoo distribution channel. The release workflow does not publish to npm, and this wiki does not claim any @shamoo/* package is registry-published. GitHub prerelease tarballs are canonical for this candidate. An explicit check such as npm view @shamoo/core@0.1.0-rc.1 version is required before any registry use.

Source fallback

If GitHub release assets are unavailable, build the exact synchronized tags from source. Do not mix branches or tags.

Runtime source build:

git clone --branch v0.1.0-rc.1 --depth 1 https://github.com/wasmake/ShamooRuntime.git
cd ShamooRuntime
./gradlew clean :bootstrap-paper:reobfJar :bootstrap-velocity:jar \
  -PprojectVersion=0.1.0-rc.1 --no-daemon --stacktrace

Install bootstrap-paper/build/libs/bootstrap-paper-0.1.0-rc.1-reobf.jar into Paper's plugins/ directory or bootstrap-velocity/build/libs/shamoo-runtime-velocity-0.1.0-rc.1.jar into Velocity's plugins/ directory. A local source build has no GitHub attestation; retain the commit ID and build logs.

TypeScript source pack:

git clone --branch v0.1.0-rc.1 --depth 1 https://github.com/wasmake/ShamooTS.git
cd ShamooTS
corepack enable
pnpm install --frozen-lockfile
NODE_OPTIONS=--max-old-space-size=8192 pnpm check
mkdir release
pnpm --recursive --filter './packages/**' pack --pack-destination "$PWD/release"

Install every tarball from that local release/ directory together. This mirrors the release workflow's packing operation, but does not create official checksums, SBOM attestations, provenance, or a GitHub release.

Sources: Runtime release guide, Runtime compatibility, and ShamooTS release guide.