← all games

action-adventure-luna-xhigh — FRICTION.md

# Friction log

This log is part of the generation run. Add an entry as soon as a surprise or slowdown appears.

## 1. create-yage dependency install did not leave an install

- Trying to scaffold a runnable game with `create-yage` and its default install.
- The scaffold command completed its copy step, but no `node_modules` or lockfile was present afterward, and `npm ls` reported every dependency as unmet. I switched the game to local `file:` dependencies against the sibling YAGE checkout so the run can stay on the measured engine source.
- Category: test-infra gap

## 2. The requested lightning package is not in the YAGE checkout

- Trying to use the requested `yagejs/lightning` surface alongside particles.
- The repository contains `@yagejs/lighting` and its `LightSource`/`LightingPlugin`, but no `@yagejs/lightning` package or export. I am using the available lighting package for radial light and drawing the set-piece lightning as a game visual with particles and blend modes.
- Category: docs ambiguity

## 3. npm install is unavailable in the scaffolded game folder

- Trying to install the local `file:` engine and addon dependencies with `npm install --ignore-scripts`.
- The command exited without output and still produced no `node_modules` or lockfile. I am switching verification to the sibling monorepo's built `dist` packages and its existing dependency installation, which avoids inventing a registry result for this private run.
- Category: test-infra gap

## 4. Synth and audio builds were out of sync

- Trying to add the required `@yagejs-addons/synth` plugin for procedural sound effects.
- The synth package had no `dist/` output, and its first build failed because the sibling audio package's built declarations did not yet expose the `registerSound` API that its source uses. Rebuilding the existing audio package and then synth restored the local package surface without changing either package's source.
- Category: docs ambiguity

## 5. Particle blend mode is newer than the installed declarations

- Trying to give ambient and combat particle emitters additive or screen blending through the documented particle component API.
- The sibling particle source and tests expose `ParticleEmitterComponent.blendMode`, but the installed declaration bundle does not. I kept particles for motion and atmosphere, and applied additive/screen blending to the game’s renderer graphics components, which are available in the installed surface.
- Category: docs ambiguity

## 6. The monorepo build includes an unrelated broken examples workspace

- Trying to rebuild every current YAGE dependency before checking this game against the latest package outputs.
- `npm run build` successfully rebuilt the engine and addon workspaces but the overall Turbo run failed in `@yagejs/examples`: its lighting example could not resolve `@yagejs/lighting`. The game’s dependency packages did finish, so I am separately forcing the exact dependency set used here and keeping the examples failure as an external verification blocker.
- Category: test-infra gap

## 7. Entity class queries and component queries are separate

- Trying to detect nearby bosses with the same `entity.has(...)` query shape used for components.
- `Entity.has` accepts component classes, so the entity subclass was incorrectly routed through the component overload after the dependency rebuild. The working entity-class check is `instanceof Boss`; component presence remains a `has(Component)` query.
- Category: API friction

## 8. The scaffold declared an unavailable unused React type package

- Trying to verify the scaffold with `npm ls --depth=0` after rebuilding the YAGE dependencies.
- The game had no React source, but `@types/react` remained in the recommended template's dev dependencies and was not present in the sibling checkout. I removed that unused declaration; React itself remains linked because the generated package still includes the UI-React runtime dependency.
- Category: test-infra gap

## 9. One entity cannot own two components of the same class

- Trying to keep the HUD background and health bar as separate `GraphicsComponent`s on the HUD root entity.
- The rebuilt core rejected the second graphics component at scene entry. I moved the health bar into a child entity; its screen-space drawing is unchanged, and the HUD now follows the engine’s one-component-per-class-per-entity rule.
- Category: API friction

## 10. Low ambient light hid otherwise readable UI

- Trying to verify the first playable frame and dialogue presentation in a browser.
- With the initial ambient lighting level, the radial lights looked atmospheric but the HUD and dialogue were too dim to read in a screenshot. I raised the lighting ambient floor while keeping the local light sources, particles, bloom, and vignette for contrast.
- Category: recipe gap

## 11. Lighting is an ordered screen overlay, not a world-only shadow pass

- Trying to keep a dark ambient grade while making the office, dungeon rooms, and HUD readable.
- The built-in renderer has no per-layer shadow mask; its radial light overlay is screen-space and relies on render-layer order. I moved `lighting` below the dialogue, inventory, and HUD layers, lowered the ambient floor, and added room-scale light sources so the world carries the darkness while UI remains unaffected.
- Category: docs ambiguity

## 12. A point ability step must use `fire`, not `enter`

- Trying to trigger the attack telegraph at the same instant as the Paper Cut ability.
- I first used `enter` for the custom step, which selected the timed-window overload and made TypeScript require `from`/`to`. The point-step overload is selected by `fire`; changing the hook made the step accept `{ at: 0 }` like the existing surge pulse.
- Category: API friction

## 13. Playwright CLI bootstrap hangs before opening the local page

- Trying to run the prescribed CLI-first browser smoke check against the fresh Vite server.
- The bundled wrapper reached `npx --yes --package @playwright/cli` and then produced no output or browser session in this environment. I am using the already-installed Playwright runtime from the sibling YAGE checkout for the same navigation, input, screenshot, and console checks.
- Category: test-infra gap

## 14. CLI-copied textures still need a scene preload declaration

- Trying to use the copied Kenney slash and brazier assets directly from `SpriteComponent`.
- The first live scene entry threw `Texture "assets/dungeon-brazier-lit.png" is not loaded`; the renderer resolves texture handles synchronously. Adding both handles to `PlayScene.preload` lets the normal scene-loading path register them before entities are built.
- Category: recipe gap

## 15. An eight-digit seam color reached Pixi's RGB converter

- Trying to draw the new glowing audit seam with a warm yellow accent.
- The live scene failed during `Graphics.stroke` because `0xfff1b94b` was an RGBA-looking literal outside the renderer's accepted 6-digit color range. Replacing it with the intended RGB value `0xf1b94b` restored scene entry.
- Category: API friction

## 16. Explicit UI layer separation was needed for the lighting contract

- Trying to keep persistent HUD, inventory, and dialogue readable over the lighting pass.
- The render tree showed the lighting layer below those layers, but the first visual pass was still too dim to use. I made the HUD a high screen layer and remapped inventory/dialogue above it, preserving their intended stack while giving the lighting overlay a clear lower boundary.
- Category: recipe gap

## 17. Entity `update()` did not drive player presentation

- Trying to rotate the player toward movement and fade the attack sprite during the Paper Cut window.
- The state and input component updated, but the `Player.update()` method was never scheduled by the engine’s component update system. Moving both presentation updates into the already-scheduled `PlayerController` fixed facing and made the attack alpha track the ability timeline.
- Category: API friction

## 18. The loaded slash texture was present but not visually legible in the first pass

- Trying to make the CLI-installed slash asset alone carry the Paper Cut attack read.
- Browser inspection confirmed the sprite was loaded, visible, and correctly sized during the ability, but its soft additive crescent was too subtle against the room treatment. I kept the asset as the animated sweep and added a crisp code-drawn range flash on the same timing so the attack shape and endpoint are unmistakable.
- Category: asset gap

## 19. Scene methods are not part of the scheduled update loop

- Trying to complete the dash trial when the player’s active dash crossed the atrium seam.
- The original check lived in `PlayScene.update()`, but YAGE’s runtime schedules component updates and systems; it does not call an arbitrary scene `update()` method. Moving the gate check into `PlayerController`, with a scene method for the story mutation, makes the input-driven crossing reliable.
- Category: API friction