A GitHub Action that exports Animated Java blueprints headlessly, in CI.
This action provisions Blockbench, installs Animated Java, and runs every .ajblueprint
under a folder through the exporter the same way clicking Export does — so a
pull request can verify that every blueprint still builds, and a release can
publish the generated data pack / resource pack.
- uses: actions/checkout@v4 - uses: Animated-Java/animated-java-ci@v1 with: blueprints-path: models
The runner must be Linux (ubuntu-latest) — Blockbench runs under xvfb.
| Input | Default | Description |
|---|---|---|
blueprints-path |
(required) | Folder searched recursively for .ajblueprint files. |
version |
latest |
Animated Java version to install: latest or a release tag (v1.10.2). |
plugin-path |
(none) | Path to a local animated_java.js to load instead of downloading a release — for testing an unreleased build. |
blockbench-version |
latest |
Blockbench version to provision: latest, beta, or an exact x.y.z. |
fail-fast |
true |
Stop at the first blueprint that fails. |
check-relative-paths |
true |
Fail a blueprint whose pack paths are absolute rather than relative to the blueprint file (see below). |
export-timeout |
300 |
Seconds allowed per blueprint. The first export also downloads that Minecraft version's assets, so keep it ample. |
github-token |
${{ github.token }} |
Used only for the GitHub API call that resolves the release asset. |
| Output | Description |
|---|---|
exported-count |
Number of blueprints exported successfully. |
failed-count |
Number of blueprints that failed. |
results |
JSON array: { blueprint, path, status, stage, errors, durationMs } per blueprint. |
The action exits non-zero if any blueprint fails, and writes a summary table to the job's step summary.
A blueprint stores where its resource pack and data pack are written. When you
save a blueprint from Blockbench on your own machine, those are usually absolute
paths (C:\Users\you\...\datapacks\pack). On a runner that folder does not
exist, so the export would fail — or, worse, write somewhere unexpected.
Set the paths in Blueprint Settings → Export to a location relative to the
.ajblueprint file, starting with ./ or ../:
models/
my_rig.ajblueprint data pack: ./datapack
datapack/ resource pack: ./resourcepack
pack.mcmeta
resourcepack/
pack.mcmeta
The target folders (with their pack.mcmeta) need to exist in the repo — commit
them alongside the blueprint. Before exporting, the action checks each blueprint
and fails it with a clear message if a required pack path is absolute or
missing. Set check-relative-paths: false to skip the check (the export will
still fail on its own if the path is unusable).
Plugin-mode blueprints export a single JSON file and are not checked.
Blockbench (~120 MB) and each Minecraft version's assets are downloaded on the
first run and kept under ~/.envbench. Cache that folder so later runs are
fast:
- uses: actions/cache@v4 with: path: ~/.envbench key: envbench-${{ runner.os }}-blockbench-latest
See examples/build-models.yml.
apt install xvfb
│
envbench ── provision an isolated Blockbench, launch it under xvfb-run
│ with the Chrome DevTools Protocol enabled
│
this action ── attach over CDP, wait for Blockbench to boot
│ load animated_java.js (release asset or plugin-path)
│
per blueprint ── load via the Animated Java codec
│ check resource/data pack paths are relative
│ AnimatedJava.exportProject(), capturing any failure message
│ close the project
│
└── write outputs + step summary, exit 1 on any failure
bun install bun run typecheck bun test # unit tests for the path checks + discovery bun run build # bundles src/ -> dist/index.cjs (committed; CI verifies it is current)
dist/index.cjs is committed because a composite action runs straight from the
checked-out repo. Rebuild it whenever src/ changes.
Other tools can drive Blockbench the same way by importing from
animated-java-ci/lib (see src/lib.ts). Bun runs it straight
from source, so it needs no build.
MIT