aego/tools/artstudio/release/README.md

Asset Studio release integration

This builder packages the existing tools/artstudio/wasm and Go Art Core. It does not replace the desktop editor, the existing Try runtime, or the normal documentation build. A snapshot is not a production release.

The manifest records two distinct engine versions. aegoVersion is the compatible release base (currently 0.12.1); engineSourceVersion is read from the exact packaged engine/config.go (currently 0.12.5-dev). Older manifests without the additive source-version field remain valid for rollback. The eight effect starters are listed separately as templates; the twelve tutorial examples remain unchanged. Both native and web creation use the shared Art Core template catalog, and GPU previews use the corresponding existing particle preset.

The native entry point uses that same art package and document operations:

go build -o .cache/bin/aego ./cmd/aego
.cache/bin/aego edit examples/platformer

Select Player and choose SpriteRenderer → Edit Sprite. For its original PNG, confirm the linked editable source before painting. The native dependency and SDL setup is the normal Aego build setup; this command does not install it.

Build and verify a new local artifact in a directory that does not yet exist:

make studio-web-build ARTSTUDIO_ID=local-01 ARTSTUDIO_OUT=/absolute/new/output
make studio-web-verify ARTSTUDIO_OUT=/absolute/new/output
go run ./tools/artstudio/release check-source -dir /absolute/new/output
go run ./tools/artstudio/release serve -dir /absolute/new/output

The server prints the standalone and documentation preview URLs. It is a development static server; the distributable directory needs no Go server in production. /editor/, /embed/ and /examples/<id>/ use the same resources. The core WASM is limited to 8 MiB raw / 3 MiB gzip. GPU Preview is loaded only when selected, from a separate 32 MiB raw / 10 MiB gzip budget in the same manifest. It uses the existing renderer, materials, alpha shadows, Bloom and CPU ParticleSystem2D in an isolated world. It excludes desktop editor, pipeline importers and unused game modules. It is not linked into the regular Demo, Playground or component Try entry points.

Height mode visualizes the data channel; it does not implement parallax. Particle flipbooks use the runtime's uniform FrameFPS derived from average duration; ordinary Art animation respects each frame's duration. Neither web preview nor export assigns assets to a local game project that is not open.

The artifact's app and docs origins must match the actual preview hosts. For real documentation integration, build into a fresh site directory with the same artifact and, preferably, the independently trusted manifest SHA:

ARTSTUDIO_ARTIFACT=/absolute/new/output \
ARTSTUDIO_MANIFEST_SHA256=<manifest-sha256> \
  go run ./cmd/aego docs build --out /absolute/new/site --engine "$PWD"

This validates the artifact, installs its localized guides and their small host assets into the site, and links the exact /r/<buildID>/ editor. No editor WASM is copied into the docs site. Existing differing files and symlink destinations are rejected, not overwritten. Without ARTSTUDIO_ARTIFACT, the existing local studio/ documentation build continues to work unchanged. The docs server's CSP must explicitly permit the exact app origin and blob: in frame-src: Firefox applies that directive to downloads from a sandboxed child iframe. The iframe allows local dialog forms while form-action 'none' still prevents network form submissions. Do not add wildcard origins or relax script rules. A local test server's policy does not establish the policy of a production deployment.

make studio-web-test runs the scoped tests. make studio-web-ci calls the strict release gate and requires its real native, browser, documentation, parity, full component Try and regression runners; missing runners are errors. The supplied defaults are tools/stage125-check.sh artstudio-native (synthetic SDL input through the real editor and GL/game scenarios) and tools/stage125-check.sh artstudio-docs (the ordinary registry/site builder with the pinned artifact). The latter creates a new $ARTSTUDIO_EVIDENCE/docs-site, or the explicit ARTSTUDIO_DOCS_SITE; arrange for the CI docs host at ARTSTUDIO_DOCS_URL to serve that directory. Production example packages additionally require AEGO_EXAMPLE_LICENSE and AEGO_EXAMPLE_LICENSE_FILE with the reviewed source license and its full terms; dependency licenses do not establish the examples' license. For a staging or alternate HTTPS host, set AEGO_EXAMPLES_URL to its exact documentation root ending in /; AEGO_EXAMPLES_VERSION selects the catalog version. An explicitly empty URL disables packages only for non-production builds. Leaving the variable unset retains gendocs' canonical default. The address and catalog contents still require independent deployment checks. The release and primary Gitea gates also run make remote-examples-check: Linux GIO dispatches the installed protocol handler in an isolated XDG profile into the actual editor confirmation window. This does not establish Windows or macOS protocol registration; those remain separate platform checks. By default its parity runner replays tools/artstudio/tests/parity.json on native Go and the served pinned WASM in Chromium and Firefox, checking every frame's albedo, normal, height and emission channels and the document topology after each operation. It records the intentionally different initial dirty state of a new web document. The runner requires the Python Playwright environment and both browser executables; an alternative real executable may be supplied with AEGO_WASM_PARITY_RUNNER. It does not replace the separate native UI scenario or test physical input and OS save. Passing a subset of tests does not authorize deployment. Production staging, activation and rollback remain separate explicit operations after all gates pass.

For the same non-production snapshot checks used by the existing Gitea workflow, install Python Playwright 1.64.1 and its Chromium and Firefox browsers, then run:

ARTSTUDIO_SNAPSHOT_DIR=/absolute/new/evidence/directory \
  bash tools/ci/artstudio_snapshot_e2e.sh

The evidence directory must not exist and must be outside the checkout. The runner builds one pinned artifact and the actual documentation site, serves both on loopback, and runs the browser, WebGL and parity suites. Optional ARTSTUDIO_APP_PORT, ARTSTUDIO_DOCS_PORT, ARTSTUDIO_PYTHON, ARTSTUDIO_CHROMIUM_EXECUTABLE and ARTSTUDIO_FIREFOX_EXECUTABLE select the local environment. It records tracked and non-ignored worktree inventories before and after the run; this is not a Git commit or proof of ignored files. The workflow uploads the snapshot and diagnostic evidence with a pinned Gitea-compatible artifact action. The remote runner and artifact service must still be checked by an actual CI run. This snapshot job never creates a release gate report or deploys anything.

The GPU E2E gate performs real HTTP/WASM hashing, lighting and alpha-shadow checks, authored normal/emission updates, Bloom, Flash/Dissolve, CPU particle flipbooks, actual context loss/restore, DPR resize and 30 document close/open resource cycles. On Linux Firefox runs headed with a real X display (or xvfb-run); an unavailable WebGL2 environment fails this gate. Screenshots, renderer/browser versions, resource counters and the exact manifest hash are saved with the result. A virtual display, SwiftShader or Mesa software renderer does not establish physical-display or hardware-GPU support. Headless pixel-core tests alone do not establish GPU support.

make ci includes the full public-component runtime coverage gate. The release gate reuses its evidence only after verifying the unchanged source inventory, the served Try WASM hash, every component/environment/action/reset observation and the actual exit code. It does not rerun a second full component suite alongside the first. An interrupted run or a report from another tree is rejected.