@waica/archetype-third-person 0.30.0 → 0.31.0

package/README.md

@@ -19,6 +19,11 @@ npx @waica/cli            # New project → 3D → Third person
 - **Camera-relative controls.** `CharacterMotor.relativeTo: 'camera'`:
   `W` walks away from the camera. `Shift` runs, `C` rolls (invulnerable while
   it lasts), `Space` jumps, a click or `J` attacks.
+- **Animation.** The Knight's idle, walk and run play one `Locomotion`
+  blend (ADR 0033): `Idle`, `Walking_A` and `Running_A` mixed by the planar
+  speed the `character` role writes to the Animator, so a half stick walks
+  slowly without its feet sliding and walk turns into run smoothly. The
+  attack and the dodge fade in over 0.05 s, the death over 0.3 s.
 - **Combat.** `MeleeAttack` strikes a box in front of the Knight's yaw;
   skeletons (the `enemy` role) patrol, chase, wind up, strike, flinch and
   die. Hits push back, blink the model and shake the camera.
@@ -30,6 +35,31 @@ npx @waica/cli            # New project → 3D → Third person
   goal chest on a raised platform: reach it to win. The blank start is a
   ground plane, a Sun and the playable Knight.
 
+## Shadows
+
+Demo and blank explicitly use `render.shadows: { quality: 'medium', maxDistance: 40 }`.
+Every Model casts/receives; the Sun and all four demo torches cast. Static and
+animated glTF assets retain their materials and gameplay.
+
+Profiles (Sun / PointLight per face): Low 1024²/256², Medium 2048²/512²,
+High 4096²/1024². Set `render.shadows.quality: 'off'` to restore the previous
+shadow-free image/cost. Existing 3D scenes change; 2D projects do not.
+
+Sun follows the active camera within finite reach. Torch shadows use the smaller
+of lighting distance and shadow reach, without shortening illumination. Each
+PointLight can add six views, hence 25 for four torches plus Sun. No FPS-based
+light caps or universal frame-rate guarantee are introduced.
+
+The editor exposes scene quality/reach and nullable per-light overrides. `null`
+inherits the scene, not zero; resetting an instance to its prefab is separate.
+See the [engine format](../engine/README.md#3d-shadows-and-migration) and
+[benchmark notes](../bench/README.md). WebGPU remains unverified on this host;
+its two external evidence gates were withdrawn from this delivery by the user,
+not marked as passing. Implementation and strict tests remain available.
+Automatic CI requires the new visual shadow checks on WebGL2; request their
+strict WebGPU counterparts with `pnpm test:e2e --webgpu-shadows`. Legacy backend
+checks remain required on both APIs.
+
 ## Controls
 
 | Action | Keys | Gamepad |

package/dist/prefabs.d.ts

@@ -1,5 +1,8 @@
 import type { PrefabJson } from '@waica/engine';
-/** The Knight's clip for each `character` state (assets/ATTRIBUTION.md). */
+/**
+ * The Knight's clip for each `character` state (assets/ATTRIBUTION.md): idle,
+ * walk and run reach theirs through the Locomotion blend (issue #205).
+ */
 export declare const KNIGHT_CLIPS: Readonly<Record<string, string>>;
 /** The Skeleton Warrior's clip for each `enemy` state (assets/ATTRIBUTION.md). */
 export declare const SKELETON_CLIPS: Readonly<Record<string, string>>;

package/dist/prefabs.js

@@ -3,7 +3,10 @@ import { CHARACTER_STATE_GRAPH, ENEMY_STATE_GRAPH } from '@waica/behaviors';
 function withClips(states, clips) {
     return Object.fromEntries(Object.entries(states).map(([name, state]) => [name, clips[name] ? { ...state, clip: clips[name] } : state]));
 }
-/** The Knight's clip for each `character` state (assets/ATTRIBUTION.md). */
+/**
+ * The Knight's clip for each `character` state (assets/ATTRIBUTION.md): idle,
+ * walk and run reach theirs through the Locomotion blend (issue #205).
+ */
 export const KNIGHT_CLIPS = {
     idle: 'Idle',
     walk: 'Walking_A',
@@ -31,19 +34,50 @@ function fixedBox(size, offset = [0, size[1] / 2, 0]) {
 function capsule(height, layer, strikes) {
     return { type: 'Collider', props: { shape: 'capsule', radius: 0.5, height, offset: [0, height / 2, 0], layer, collidesWith: [strikes] } };
 }
+/** Every character and level piece participates in the scene's shadows. */
+function gltfModel(src) {
+    return { type: 'Model', props: { src, castShadows: true, receiveShadows: true } };
+}
+/**
+ * The Knight's walk cycle (issue #205 CA-15): Idle, Walking_A and Running_A
+ * mixed by the planar speed the `character` role writes, at the motor's
+ * speeds (still, `speed` 6 and `runSpeed` 10), so a half stick walks slowly
+ * without sliding its feet. idle, walk and run all play it: switching among
+ * them keeps it playing, and the smoothed speed does the transition.
+ */
+const LOCOMOTION = 'Locomotion';
+const LOCOMOTION_BLEND = {
+    param: 'speed',
+    points: [{ clip: KNIGHT_CLIPS.idle, at: 0 }, { clip: KNIGHT_CLIPS.walk, at: 6 }, { clip: KNIGHT_CLIPS.run, at: 10 }],
+    smoothing: 0.15,
+};
 const PLAYER = {
     waicaPrefab: 1,
     type: 'character',
     components: [
-        { type: 'Model', props: { src: 'waica:tp-knight' } },
+        gltfModel('waica:tp-knight'),
         {
             type: 'Animator',
             props: {
                 initialClip: 'Idle',
-                clips: { Jump_Start: { loop: false }, '1H_Melee_Attack_Chop': { loop: false }, Dodge_Forward: { loop: false }, Death_A: { loop: false } },
+                // The attack and the dodge answer the press at once; the death settles in slower.
+                clips: {
+                    Jump_Start: { loop: false },
+                    '1H_Melee_Attack_Chop': { loop: false, fade: 0.05 },
+                    Dodge_Forward: { loop: false, fade: 0.05 },
+                    Death_A: { loop: false, fade: 0.3 },
+                },
+                blends: { [LOCOMOTION]: LOCOMOTION_BLEND },
+            },
+        },
+        {
+            type: 'StateMachine',
+            props: {
+                role: 'player',
+                initial: CHARACTER_STATE_GRAPH.initial,
+                states: withClips(CHARACTER_STATE_GRAPH.states, { ...KNIGHT_CLIPS, idle: LOCOMOTION, walk: LOCOMOTION, run: LOCOMOTION }),
             },
         },
-        { type: 'StateMachine', props: { role: 'player', initial: CHARACTER_STATE_GRAPH.initial, states: withClips(CHARACTER_STATE_GRAPH.states, KNIGHT_CLIPS) } },
         capsule(2.3, 'player', 'enemy'),
         { type: 'RigidBody', props: { type: 'kinematic' } },
         { type: 'CharacterMotor', props: { relativeTo: 'camera' } },
@@ -60,7 +94,7 @@ const SKELETON = {
     waicaPrefab: 1,
     type: 'character',
     components: [
-        { type: 'Model', props: { src: 'waica:tp-skeleton-warrior' } },
+        gltfModel('waica:tp-skeleton-warrior'),
         {
             type: 'Animator',
             props: { initialClip: 'Walking_A', clips: { '1H_Melee_Attack_Chop': { loop: false }, Hit_A: { loop: false }, Death_A: { loop: false } } },
@@ -100,7 +134,7 @@ export const THIRD_PERSON_PREFABS = {
         waicaPrefab: 1,
         type: 'object',
         components: [
-            { type: 'Model', props: { src: 'waica:tp-banner' } },
+            gltfModel('waica:tp-banner'),
             // A wall banner: its origin on the wall, its sensor and spawn on the floor in front of the wall (local +z).
             { type: 'Collider', props: { shape: 'box', size: [2, 3, 2], offset: [0, 1.5, CHECKPOINT_REACH], sensor: true, layer: 'world' } },
             { type: 'Checkpoint', props: { spawnOffset: [0, 0, CHECKPOINT_REACH] } },
@@ -110,26 +144,26 @@ export const THIRD_PERSON_PREFABS = {
         waicaPrefab: 1,
         type: 'object',
         components: [
-            { type: 'Model', props: { src: 'waica:tp-chest' } },
+            gltfModel('waica:tp-chest'),
             { type: 'Collider', props: { shape: 'box', size: [2.4, 2, 2.4], offset: [0, 1, 0], sensor: true, layer: 'world' } },
             { type: 'GoalChest' },
         ],
     },
-    'tiles/wall': { waicaPrefab: 1, type: 'tile', components: [{ type: 'Model', props: { src: 'waica:tp-wall' } }, fixedBox([4, 4, 1])] },
+    'tiles/wall': { waicaPrefab: 1, type: 'tile', components: [gltfModel('waica:tp-wall'), fixedBox([4, 4, 1])] },
     'tiles/floor': {
         waicaPrefab: 1,
         type: 'tile',
-        components: [{ type: 'Model', props: { src: 'waica:tp-floor' } }, fixedBox([4, 0.2, 4], [0, -0.05, 0])],
+        components: [gltfModel('waica:tp-floor'), fixedBox([4, 0.2, 4], [0, -0.05, 0])],
     },
-    'tiles/step': { waicaPrefab: 1, type: 'tile', components: [{ type: 'Model', props: { src: 'waica:tp-foundation' } }, fixedBox([2.2, 2, 2.2])] },
-    'tiles/column': { waicaPrefab: 1, type: 'tile', components: [{ type: 'Model', props: { src: 'waica:tp-pillar' } }, fixedBox([1.5, 4, 1.5])] },
+    'tiles/step': { waicaPrefab: 1, type: 'tile', components: [gltfModel('waica:tp-foundation'), fixedBox([2.2, 2, 2.2])] },
+    'tiles/column': { waicaPrefab: 1, type: 'tile', components: [gltfModel('waica:tp-pillar'), fixedBox([1.5, 4, 1.5])] },
     'tiles/torch': {
         waicaPrefab: 1,
         type: 'tile',
         components: [
-            { type: 'Model', props: { src: 'waica:tp-torch' } },
+            gltfModel('waica:tp-torch'),
             fixedBox([0.6, 1.1, 0.7], [0, 0.15, 0.3]),
-            { type: 'PointLight', props: { color: '#ffb060', intensity: 14, distance: 9, offsetY: 0.6, offsetZ: 0.6 } },
+            { type: 'PointLight', props: { color: '#ffb060', intensity: 14, distance: 9, offsetY: 0.6, offsetZ: 0.6, castShadows: true } },
         ],
     },
 };

package/dist/scene-default.js

@@ -19,14 +19,18 @@ function orbitCamera() {
 function threeDScene(entities) {
     return {
         waicaScene: 3,
-        render: { space: '3d', lighting: { ambient: { color: '#b8c8ff', intensity: 0.55 } } },
+        render: {
+            space: '3d',
+            lighting: { ambient: { color: '#b8c8ff', intensity: 0.55 } },
+            shadows: { quality: 'medium', maxDistance: 40 },
+        },
         simulation: { gravity: [0, -9.81, 0] },
         camera: orbitCamera(),
         entities,
         ui: ['player-health', 'controls-hint'],
     };
 }
-const SUN = { name: 'Sun', components: [{ type: 'Sun', props: { direction: [-0.5, -1, -0.35], intensity: 2.2 } }] };
+const SUN = { name: 'Sun', components: [{ type: 'Sun', props: { direction: [-0.5, -1, -0.35], intensity: 2.2, castShadows: true } }] };
 /** Half the courtyard's side: 5 × 5 floor tiles of 4 units, walls on the edge. */
 const HALF = 10;
 const TILE_CENTERS = [-8, -4, 0, 4, 8];
@@ -91,7 +95,7 @@ export const THIRD_PERSON_BLANK_SCENE = threeDScene([
         name: 'Ground',
         scale: [24, 1, 24],
         components: [
-            { type: 'Model', props: { shape: 'plane', color: '#5a6b4e' } },
+            { type: 'Model', props: { shape: 'plane', color: '#5a6b4e', castShadows: true, receiveShadows: true } },
             { type: 'Collider', props: { shape: 'box', size: [1, 1, 1], offset: [0, -0.5, 0], layer: 'world' } },
         ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/archetype-third-person",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Waica third-person archetype — an orbit camera, camera-relative controls and 3D melee combat in a dungeon courtyard",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@waica/behaviors": "^0.30.0",
-    "@waica/engine": "^0.30.0"
+    "@waica/behaviors": "^0.31.0",
+    "@waica/engine": "^0.31.0"
   }
 }