create-aura3d 3.0.1 → 4.0.0

package/skills/manifest.json

@@ -0,0 +1,163 @@
+{
+  "schema": "aura3d.skills/1.0",
+  "cliVersion": "3.0.1",
+  "docsBase": "https://github.com/auraoneai/aura3d/blob/main/",
+  "coreSet": [
+    "aura3d-core",
+    "aura3d-art-direction",
+    "aura3d-assets",
+    "aura3d-evidence-review",
+    "aura3d-scene-authoring"
+  ],
+  "skills": {
+    "aura3d-core": {
+      "tier": "core",
+      "prd": "C1"
+    },
+    "aura3d-scene-authoring": {
+      "tier": "core",
+      "prd": "C2"
+    },
+    "aura3d-assets": {
+      "tier": "core",
+      "prd": "C3"
+    },
+    "aura3d-evidence-review": {
+      "tier": "core",
+      "prd": "C4"
+    },
+    "aura3d-art-direction": {
+      "tier": "core",
+      "prd": "QR13"
+    },
+    "aura3d-browser-game": {
+      "tier": "domain",
+      "prd": "D1"
+    },
+    "aura3d-character-animation": {
+      "tier": "domain",
+      "prd": "D2"
+    },
+    "aura3d-animation-studio": {
+      "tier": "domain",
+      "prd": "D3"
+    },
+    "aura3d-threejs-migration": {
+      "tier": "domain",
+      "prd": "D4"
+    },
+    "meshy-cli": {
+      "tier": "asset",
+      "prd": "P1"
+    },
+    "aura3d-materials-environments": {
+      "tier": "asset",
+      "prd": "P2"
+    },
+    "aura3d-game-art": {
+      "tier": "asset",
+      "prd": "P3"
+    },
+    "aura3d-retexture": {
+      "tier": "asset",
+      "prd": "P4"
+    },
+    "aura3d-performance": {
+      "tier": "later",
+      "prd": "L1"
+    }
+  },
+  "templates": {
+    "product-viewer": [
+      "aura3d-materials-environments",
+      "aura3d-retexture",
+      "meshy-cli"
+    ],
+    "cinematic-scene": [
+      "aura3d-materials-environments",
+      "aura3d-character-animation"
+    ],
+    "mini-game": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "racing-starter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "falling-blocks-starter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "fighting-game": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-character-animation",
+      "aura3d-game-art"
+    ],
+    "arena-shooter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "character-controller": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-character-animation"
+    ],
+    "animation-channel": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "prompt-animation-channel": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "animation-studio": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "episode-builder": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "premium-product-viewer": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "architecture-interior": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "material-authoring": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "asset-inspector": [
+      "aura3d-threejs-migration"
+    ],
+    "character-viewer": [
+      "aura3d-threejs-migration",
+      "aura3d-character-animation"
+    ],
+    "postprocess-scene": [
+      "aura3d-threejs-migration"
+    ],
+    "custom-scene": [
+      "aura3d-threejs-migration"
+    ],
+    "large-scene": [
+      "aura3d-threejs-migration",
+      "aura3d-performance"
+    ]
+  },
+  "clients": {
+    "claude": ".claude/skills",
+    "cursor": ".cursor/skills",
+    "generic": ".agents/skills",
+    "copilot": ".github/skills"
+  }
+}

package/skills/meshy-cli/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: meshy-cli
+description: Guides safe Meshy 3D generation, retexture, remesh, rigging, and animate work through the pinned official CLI and admits results with `aura3d assets import-meshy`. Use when the catalog has no clean candidate, or when planning, generating, resuming, downloading, post-processing, or admitting Meshy assets for Aura3D.
+---
+
+# Meshy CLI
+
+The installed official Meshy CLI is the command authority. Do not reproduce
+its API or trust remembered flags. Paid-generation controls are shared in
+[boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Decide the look before writing the generation prompt — the recipe row's palette
+and material mood belong in the Meshy text ("matte ceramic", "sun-faded
+plastic") so the returned PBR set lands inside the frame's lighting instead of
+fighting it. Judge the result under the scene's look preset, not in a neutral
+viewer.
+
+## Establish the contract
+
+1. Run `meshy --version` and require the repository pin `0.2.0`.
+2. Read `meshy --help`, `meshy resources`, and `meshy <resource> create --help`
+   for every resource you will call.
+3. Run `npx @aura3d/cli@latest --help` and confirm `assets import-meshy` and
+   its `--profile prop|environment|vehicle|humanoid` values.
+4. Confirm the catalog was tried first (`aura3d-assets`) and its rejection
+   reasons were reported. For the full upstream agent skill, review and pin a
+   revision of [meshy-3d-agent](https://github.com/meshy-dev/meshy-3d-agent)
+   before installing; do not copy its text here.
+
+## Decision tree
+
+Start from the closest existing mesh and pick the smallest operation:
+
+| Situation | Operation |
+| --- | --- |
+| Geometry and topology are right, look is wrong | `meshy retexture create` (hand the look to `aura3d-retexture` first) |
+| Look is right, triangle count or topology fails the profile | `meshy remesh create --target-polycount N` |
+| Textured humanoid, static, needs a skeleton | `meshy rigging create --height-meters M` |
+| Rig succeeded, a named action is missing | `meshy animate create --rig-task-id <id> --action-id N` |
+| Nothing usable exists | `meshy make "<prompt>"` or `meshy make ./ref.png` |
+| Only format or real-world size is wrong | `meshy convert` or `meshy resize` |
+
+Reject instead of generating when the subject is a named real product,
+brand, or person whose rights you cannot evidence; when rights evidence for
+the output cannot be recorded; when the user has not approved a maximum; or
+when a catalog candidate already passes the rubric.
+
+## Procedure
+
+1. Plan: `meshy make "<prompt>" --dry-run` and show the steps and estimate.
+   For single resources, read the create help and state the planned inputs.
+2. Get explicit approval for the maximum, then pass `--max-credits <approved>`.
+3. Run, preferring `--async` when other work can proceed. Persist task IDs
+   and provider resume hints in ignored local state. Resume a completed
+   preview; never recreate paid work that succeeded.
+4. Download immediately: `-o artifacts/meshy/<asset>/`. Never overwrite an
+   existing output directory without direct instruction.
+5. Texture precedence on `retexture create`: `--input-task-id` wins over
+   `--model-url`; `--multiview-image-urls` excludes both `--text-style-prompt`
+   and `--image-style-url`, which exclude each other. Keep
+   `--enable-original-uv true` to preserve an admitted mesh's UVs, and keep
+   `--enable-pbr true` so normal, metallic, roughness, and emission maps exist.
+6. Profile traps, from the Aura3D admission budgets:
+
+   | `--profile` | Max triangles | Min triangles | Max textures | Max texture px |
+   | --- | --- | --- | --- | --- |
+   | `prop` | 100,000 | none | 8 | 4096 |
+   | `vehicle` | 250,000 | 1,000 | 12 | 4096 |
+   | `humanoid` | 150,000 | 3,000 | 12 | 4096 |
+   | `environment` | 500,000 | none | 16 | 8192 |
+
+   Meshy `--texture-resolution` defaults to `4k`; `8k` fails every profile
+   except `environment`. With `--enable-pbr` each map counts toward the
+   texture limit. Non-indexed geometry leaves the triangle check `unproven`.
+   Omitting `--profile` infers it from `--role` (`character` to humanoid,
+   `vehicle` to vehicle, `world`/`environment`/`track` to environment, else
+   prop). Remesh defaults to 30,000; about 10,000 rigs well.
+7. Admit the local output with rights evidence.
+
+   ```bash
+   npx @aura3d/cli@latest assets import-meshy artifacts/meshy/arena-relic/ \
+     --name arenaRelic --rights-evidence artifacts/meshy/arena-relic/rights.json \
+     --profile prop --role prop --thumbnail artifacts/meshy/arena-relic/thumbnail.png
+   ```
+
+   Use `--file` when the run has several GLBs. Import defaults to
+   `--quality candidate` and refuses release certification. Read the
+   admission `blockers` and `unproven` lists; `routeReady: false` is a result
+   to report.
+8. Rig handoff: after importing a rigged humanoid, inspect it and map clips
+   before any code names them, then load `aura3d-character-animation`.
+
+   ```bash
+   npx @aura3d/cli@latest assets inspect public/aura-assets/<file>.glb --animation --humanoid --skeleton
+   npx @aura3d/cli@latest assets validate-animation --clips <from inspect> \
+     --map idle=<clip>,walk=<clip>,run=<clip> --require idle,walk,run --require-rig
+   ```
+
+9. Use only the generated `assets.<key>` in code. Provider URLs, task IDs,
+   and `artifacts/meshy` paths never appear in route source. Send review to
+   `aura3d-evidence-review`.
+
+## Safety
+
+- Keep credentials out of arguments, prompts, logs, commits, and output. Use
+  OAuth locally (`meshy auth login`) or runtime `MESHY_API_KEY` injection in
+  authorized CI. Never use `auth login --with-key` with a pasted key.
+- Send Meshy only intentional prompts and selected media, never repository
+  source or unrelated user data.
+- Propagate Meshy exit codes (3 auth, 4 validation, 6 rate limit, 8 timeout,
+  9 credits exhausted). Prism or agent-capacity failures are separate issues.
+
+## Stop and report
+
+- No approved maximum: stop after the dry run and present the plan.
+- Exit code 9 or a plan above the approved maximum: stop; do not split the
+  job to stay under the cap.
+- Admission reports blockers for the chosen profile: keep the file as a
+  rejected local candidate, report the failing checks, and label the route
+  `prototype` or `blocked`.
+- `validate-animation` reports missing clips: do not name them in code;
+  report the gap and consider `meshy animate` with fresh approval.
+- Rights evidence cannot be produced: do not import.
+
+## References
+
+- [Boundaries](../aura3d-core/references/boundaries.md)
+- [Aura3D Meshy pipeline](https://github.com/auraoneai/aura3d/blob/main/docs/meshy-cli.md)
+- [Admission budgets source](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/meshy/admission.ts)
+- [Meshy CLI](https://github.com/meshy-dev/meshy-cli)
+- [Meshy API docs](https://docs.meshy.ai/en/api)

package/templates/animation-channel/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# Aura3D agent instructions
+
+Read ./llms.txt first. Read the `aura3d-art-direction` skill. Every scene gets a look. Run the look-dev loop (`aura3d look capture` → judge → iterate) before calling a scene done.

package/templates/animation-channel/.github/workflows/aura3d-lookdev.yml

@@ -0,0 +1,67 @@
+name: Aura3D look-dev
+
+# Captures this scene's screenshot tests on an Apple-silicon GPU runner
+# (ANGLE Metal) and uploads the report as the `lookdev` artifact.
+# `aura3d look capture --runner gh-actions` dispatches this workflow and
+# downloads the artifacts; it can also be run manually from the Actions tab.
+# No secrets are used; workflow_dispatch only — never runs forked code.
+
+on:
+  workflow_dispatch:
+    inputs:
+      shots:
+        description: "Shot names to capture (comma-separated; the template's defaults when empty)"
+        required: false
+        default: ""
+      viewports:
+        description: "Viewport names (comma-separated; the template's defaults when empty)"
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  capture:
+    name: Look-dev captures (macos-14, ANGLE Metal)
+    runs-on: macos-14
+    timeout-minutes: 45
+    env:
+      QRC_GPU_ARGS: "--use-angle=metal --enable-gpu --ignore-gpu-blocklist"
+      A3D_LOOKDEV_SHOTS: ${{ inputs.shots }}
+      A3D_LOOKDEV_VIEWPORTS: ${{ inputs.viewports }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build the app
+        run: npm run build
+
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium
+
+      - name: Capture screenshots
+        run: npx playwright test tests/screenshot.spec.ts --reporter=line
+        env:
+          CHROMIUM_FLAGS: ${{ env.QRC_GPU_ARGS }}
+
+      - name: Upload look-dev artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lookdev
+          path: |
+            tests/reports/**
+          if-no-files-found: warn
+          retention-days: 30

package/templates/animation-channel/AGENTS.md

@@ -0,0 +1,3 @@
+# Aura3D agent instructions
+
+Read ./llms.txt first. Read the `aura3d-art-direction` skill. Every scene gets a look. Run the look-dev loop (`aura3d look capture` → judge → iterate) before calling a scene done.

package/templates/animation-channel/package.json

@@ -12,8 +12,9 @@
     "test:negative-failed-puppets": "playwright test tests/concept-2-5d.spec.ts tests/puppet-2d.spec.ts tests/image-puppet.spec.ts tests/concept-2-5d-animation.spec.ts tests/puppet-2d-animation.spec.ts tests/image-puppet-animation.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "3.0.1",
-    "@aura3d/navigation-recast": "3.0.1"
+    "@aura3d/engine": "4.0.0",
+    "@aura3d/navigation-recast": "4.0.0",
+    "@aura3d/assets": "4.0.0"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",

package/templates/animation-channel/src/main.ts

@@ -7,7 +7,7 @@ import {
   game,
   installShotPlayback,
   labels,
-  lights,
+  looks,
   material,
   model,
   primitives,
@@ -132,9 +132,12 @@ installSampleEpisodeVisual({
   usesTypedAssets: missingAnimationCharacterAssets.length === 0
 });
 
+const LOOK_ID = "character-showcase" as const;
+
 const app = createAuraApp("#app", {
   scene: scene()
-    .background("#081b2a")
+    .background(looks.describe(LOOK_ID).v0.background)
+    .add(looks.preset(LOOK_ID))
     .addMany(createAuraRenderedAnimationScene())
     .add(createCharacterBody("miko", "Miko", "miko", [-0.72, 0.08, -0.34], [0.32, 0.42, 0.32], 0.9, "#7de2ff"))
     .add(createMouthCard("miko:mouth", "Miko", [-3.2, -3.2, -3.2], "#f8fff2"))
@@ -159,7 +162,6 @@ const app = createAuraApp("#app", {
         .scale([0.12, 0.24, 0.04])
     )
     .add(labels.hud(firstCaption?.text ?? firstStoryboardShot?.storyBeat ?? "Aura3D animation channel"))
-    .add(lights.studio({ intensity: 1.2 }))
     .add(effects.bloom({ intensity: 0.18, color: "#7de2ff" }))
     .camera(camera.perspective({ position: [0, 1.18, 4.4], target: [0, 0.82, -0.45], fov: 38 })),
   diagnostics: true
@@ -272,9 +274,6 @@ function createAuraRenderedAnimationScene() {
     primitives.box({ name: "Aura3D broom bristles", material: bloomGold }).position(-0.55, 0.14, -0.18).rotate(0, 0, -0.25).scale([0.18, 0.1, 0.04]),
     ...createGlowStones(),
     ...createMoonLilies(),
-    lights.ambient({ intensity: 0.2, color: "#b9f2ff" }),
-    lights.point({ name: "Aura3D moon garden cyan key", position: [-1.8, 2.4, 1.2], color: "#7de2ff", intensity: 2.8 }),
-    lights.point({ name: "Aura3D moon garden warm robot rim", position: [1.8, 1.7, 0.8], color: "#ffe18e", intensity: 2.0 })
   ];
 }
 

package/templates/animation-channel/src/render-plan.ts

@@ -1,15 +1,12 @@
 import {
-  collectPromptAnimationEvidence,
   createAudioStemManifest,
   createAuraVoiceBridgePackage,
   createAuraVoiceVisemeTrack,
-  createCaptionTimingProof,
   createGlbBlendshapeVisemeCue,
   createAnimationPerformanceCoverage,
   createAnimationRenderOutputPackageMetadata,
   createPrimitiveMouthVisemeCues,
   createPromptAnimationDeterministicScreenshotFixtureMetadata,
-  evaluatePromptAnimationPublishReadiness,
   defineDubMap,
   glbVisemeBlendshapeExample,
   primitiveMouthVisemeExample,
@@ -17,6 +14,11 @@ import {
   sampleVisemeTrack,
   validateAuraVoiceBridgePackage
 } from "@aura3d/engine";
+import {
+  collectPromptAnimationEvidence,
+  createCaptionTimingProof,
+  evaluatePromptAnimationPublishReadiness
+} from "@aura3d/engine/devtools";
 import {
   episode,
   episodeAudioCues,