Common Failures and Fixes

Use this page when the game does not create, run, render, load assets, or publish the way you expected.

Table of Contents

1. Create and Install Problems
2. Project Loop Problems
3. Asset and Media Problems
4. 3D and Imported Content Problems
5. Publish and Large-Asset Problems

1. Create and Install Problems

`auramaxx create --template ...` rejects a template you expected

The create wrapper now accepts the shipped template catalog directly, so a rejection usually means the template name is misspelled or older docs were describing a previous stage.

Fix:

• use the current canonical names such as 2d-adventure, 3d-adventure, 2d-shooter, 3d-platformer, 3d-collectathon, deckbuilder-2d, local-multiplayer, or blank
• or use the 2d / 3d aliases when you want the canonical adventure starters
• then confirm the current template behavior in Creating a New Game

The created project does not run immediately

Fix:

1. run npm install if you created with --skip-install
2. run npm run dev
3. read src/main.js, src/runtime/, and scenes/ before reorganizing the scaffold

2. Project Loop Problems

Session/state/action commands do not behave the way you expect

Remember the model:

• auramaxx play and auramaxx run --session launch an AuraJS process from the current project
• auramaxx session ... controls that AuraMaxx-launched session
• this is not a generic attach API for arbitrary foreign processes

Fix:

• confirm the exact CLI behavior in CLI, Create, Build, Dev, Test, and Project Files

The game state is getting messy

Fix:

• keep shared mutable state in src/runtime/app-state.js
• keep scene-local mutable state in sceneState
• keep defaults and tuning in config/
• keep authored definitions in content/

If you are mixing those, stop and read Handling State and Content.

3. Asset and Media Problems

An asset loads locally but fails in another environment

Fix:

• prefer explicit, known-good formats
• check the current truth in Assets and Media
• do not assume codec behavior that the docs do not explicitly promise

Native `.mp4` does not load

Current native .mp4 support depends on desktop tooling.

Fix:

• verify ffmpeg and ffprobe are available
• then confirm the exact behavior in docs/native-mp4-video-contract-v1.md

4. 3D and Imported Content Problems

The first 3D scene still does not render

Fix the base scene in this order:

1. camera
2. light
3. mesh
4. material
5. draw submission

Do not debug imported content and physics before the base scene is known-good.

Use:

• Getting Started 3D
• Draw3D, Camera, Lighting, and PostFX Exact Reference

Imported glTF content behaves differently than expected

Fix:

• confirm the current import surface in 09 Meshes, Materials, Scene3D, glTF, and Skinned Mesh
• then use Scene3D, Mesh, Material, glTF, and Avatar Exact Reference

5. Publish and Large-Asset Problems

I am unsure whether to use npm or self-hosted assets

Use this rule:

• code/bootstrap publish path: auramaxx publish
• large asset path today: self-hosted external assets

Read:

• Publishing and Large Assets

Packaged `play` or `join` fails after moving assets out of the package

Fix:

• verify the external-asset config and manifest URLs are correct
• confirm you are on the self-hosted external-asset lane, not mixing it with the normal bundled-asset lane
• use the current exact contract docs linked above

If You Still Need Exactness

Use the smallest exact-reference page that matches the failing subsystem:

• Lifecycle, Window, Input, and 2D Camera Exact Reference
• Draw2D, Assets, Audio, Storage, and Math Exact Reference
• Animation, Scenes, State, Tilemaps, and ECS Exact Reference
• Draw3D, Camera, Lighting, and PostFX Exact Reference
• Scene3D, Mesh, Material, glTF, and Avatar Exact Reference
• Physics3D, Terrain, Navmesh, Character3D, and Compute Exact Reference
• Net, Multiplayer, and Runtime Sessions Exact Reference