Publishing and Large Assets

Use this page when the game is ready to leave the local dev loop and you need the truthful publish and large-asset story.

Table of Contents

1. Normal Publish Path
2. When To Use Self-Hosted Assets
3. Self-Hosted Project Example
4. Recommended Operator Order

1. Normal Publish Path

For most games, the public publish lane is still:

auramaxx publish --dry-run
auramaxx publish

Use this when:

• the package size is still reasonable for npm delivery
• the game can ship with bundled local assets
• you do not need an external asset CDN or external manifest indirection yet

This remains the canonical public path.

2. When To Use Self-Hosted Assets

Use the self-hosted external-asset lane when the package would become too large or when you need assets to live on your own CDN/storage instead of inside the npm tarball.

Current public truth:

• AuraJS supports a provider-neutral self-hosted asset manifest/config path
• packaged play and join can hydrate self-hosted assets before launch
• the normal public publish center is auramaxx publish

3. Self-Hosted Project Example

Author the game normally and keep your assets where they already live during development:

my-game/
├─ assets/
│  ├─ audio/
│  ├─ textures/
│  └─ video/
├─ src/
├─ package.json
└─ build/

If auramaxx publish --dry-run says the payload is too large, generate the self-hosted config after you build:

auramaxx external-assets generate --public-base-url https://cdn.example.com/games

That adds:

• aura.external-assets.json in the project root
• staged upload/manifests under .aura/external-assets/<project>/<release>/

Example layout after generation:

my-game/
├─ assets/
├─ aura.external-assets.json
├─ build/
├─ package.json
├─ src/
└─ .aura/
   └─ external-assets/
      └─ my-game/
         └─ 1.2.3/
            ├─ publish-plan.json
            └─ payload/
               ├─ blobs/
               └─ releases/
                  └─ my-game/
                     └─ 1.2.3/
                        ├─ build-manifest.json
                        ├─ assets-manifest.json
                        └─ release.json

The generated root config looks like:

{
  "schema": "aurajs.external-assets-config.v1",
  "mode": "self-hosted",
  "project": "my-game",
  "release": "1.2.3",
  "channel": "latest",
  "provider": "self-hosted",
  "releaseManifestUrl": "https://cdn.example.com/games/releases/my-game/1.2.3/release.json",
  "assetsManifestUrl": "https://cdn.example.com/games/releases/my-game/1.2.3/assets-manifest.json",
  "generatedAt": "<generated-at>"
}

4. Recommended Operator Order

For a normal published game:

1. keep the project runnable locally with npm run dev and npm run play
2. run auramaxx publish --dry-run
3. publish with auramaxx publish

For a large game with self-hosted assets:

1. keep code/bootstrap publishing on the npm lane
2. move large assets to the self-hosted external-asset lane
3. generate aura.external-assets.json and upload the staged manifests plus blobs
4. publish the slim npm package after the hosted URLs are live

Related Docs

• Creating a New Game
• CLI, Create, Build, Dev, Test, and Project Files
• Common Failures and Fixes