## Description
Adds the Godot Stage rim light pipeline and development observation
tooling.
- Replaces the old avatar glow-only compositor path with a staged
post-process compositor.
- Adds avatar-scoped edge light, glow, material overlay, and final
colour mapping stages.
- Implements a dev observation adapter for exporting
viewport/render-stage artefacts.
- Adds visual verification tooling and baseline docs for Godot Stage
rendering work.
- Documents the technical art workflow and rendering effect behaviour.
## Summary
This PR adds the current Stage Godot avatar presentation path:
avatar-only same-frame glow plus tuned toon color mapping.
<img width="994" height="951" alt="屏幕截图 2026-06-02 015159"
src="https://github.com/user-attachments/assets/feb94b95-745f-4b47-aba2-0289dafecd1c"
/>
<img width="1769" height="1279" alt="屏幕截图 2026-06-02 021212"
src="https://github.com/user-attachments/assets/d4437dc2-e859-42ca-b3fd-0a90e55d641b"
/>
## Design
The implementation uses three layers:
1. Base avatar material rendering still comes from the vendored V-Sekai
MToon shader.
2. `StageAvatarGlowRuntime` marks visible avatar meshes through a
depth-tested `MaterialOverlay` stencil pass.
3. `StageAvatarGlowCompositorEffect` reads that stencil mask in the same
frame, extracts avatar pixels, builds the glow pyramid, composites
glare, and applies the current NAES/toon color mapping.
This avoids Godot Environment Glow because that path is global. Here,
source selection needs to be avatar-specific and controlled by the stage
runtime.
It also avoids an extra SubViewport path because prior testing showed
camera-motion lag. The compositor path keeps the effect in the same
render frame.
## Stage Baseline
`StageVisualPreset` now keeps the stage environment neutral for this
effect:
- skybox is visible as background only
- skybox does not drive avatar/ground ambient light
- reflected light is disabled
- Godot Environment Glow is disabled
- Godot tonemap/adjustment stay neutral
- custom color mapping runs in the compositor
## Notes
`StageAvatarGlowCompositorEffect` currently owns both avatar glow and
toon color mapping. That is acceptable for this PR because it is the
only custom stage compositor today.
Before adding rim light, screen-space outlines, or more post effects,
compositor ownership should be split from individual features so effects
can register passes instead of replacing `Camera3D.Compositor`
independently.
## Summary
Add the G1.3 default visual baseline for `stage-tamagotchi-godot`.
This moves the Godot stage from a model-loading/runtime skeleton toward
a default presentation stage: fixed sky environment, visual grid ground,
centre marker, fixed lighting rig, camera ground constraint, and focused
material/rendering verification.
## Changes
- Add a fixed runtime visual preset for the Godot stage
- WorldEnvironment with the existing stage-ui-three HDRI skybox
- visual-only grid ground at world `Y=0`
- centre `T` marker at the world origin
- fixed directional light rig replacing the old single `OmniLight3D`
- Reuse the existing three-stage HDRI asset
- resolve
`packages/stage-ui-three/src/components/Environment/assets/sky_linekotsi_23_HDRI.hdr`
from a workspace checkout
- do not copy or move the asset into Godot `assets/`
- keep release packaging for the shared HDRI as a follow-up
- Add camera ground constraint in view-state rules
- clamp camera position `Y` during view-state normalisation / commit
- applies uniformly to local input, settings-driven patches, and future
remote/agent patches
- Patch vendored Godot MToon shader behaviour
- disable implicit WorldEnvironment ambient light for MToon materials
- use Godot alpha scissor / alpha-to-coverage path for cutout MToon
variants
- document the local vendor patch and removal conditions in
`docs/vendor-patches.md`
- Improve Godot rendering defaults
- enable 3D MSAA
- render 3D at 2x scale to avoid low-DPI/viewport scaling aliasing
- Add verification harnesses
- C# engine-local checks for camera ground constraint and HDRI asset
resolution
- Godot material rendering check scene for AvatarSample A/B material
import coverage
- Clean stage root presentation
- remove the old on-screen runtime status label
- keep Electron bridge and scene/view runtime wiring intact
## Notes
The HDRI path resolution is intentionally workspace-only in this PR.
Release packaging for sharing the three-stage HDRI with the exported
Godot sidecar remains a follow-up.
The MToon shader changes are deliberate vendor patches, recorded in
`docs/vendor-patches.md`, because `ambient_light_disabled`,
`alpha_to_coverage`, and alpha scissor behaviour are shader-level
changes rather than runtime material parameters.
The material rendering check validates imported material structure, not
visual golden output.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
- Fix the first Live2D -> VRM switch camera regression where
OrbitControls could clamp the camera into the model.
- Remove the VRM render scale control from the model settings panel.
- Remove the now-unused `settings.vrm.render-scale` locale entries.
- Ignore Godot/.NET `bin/` and `obj/` build artifacts under
`engines/stage-tamagotchi-godot`.
## Root Cause
On the first VRM load, `OrbitControls` can mount before the VRM
bootstrap writes a real `modelSize`. The previous watcher copied
`modelSize.z = 0` into `minDistance` and `maxDistance`, so later camera
updates were clamped onto the target before the bootstrap camera pose
finished applying.
## Changes
- Skip OrbitControls distance-bound updates until `modelSize.z` is
finite and non-zero.
- Keep the render scale runtime state intact, but remove the VRM
settings UI entry so it is no longer hot-updated from the panel.
- Add Godot project ignores for local .NET build output.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
This PR adds the first usable camera and view-state loop for the
experimental Godot stage.
The main design direction is that Godot owns the stage view state, while
Electron and the settings page act as lifecycle/transport/control
surfaces. The settings UI can now edit Godot camera state, and camera
changes from the Godot window can flow back to the UI.
## What Changed
- Added the shared Godot view-state contract for camera pose, avatar
bounds, snapshots, patches, and errors.
- Added Electron main bridge APIs for Godot status, scene input, view
snapshots, and view patches.
- Added Godot-side camera runtime:
- initial camera bootstrap from loaded avatar bounds
- avatar facing normalisation
- orbit, pan, wheel movement, and WASD-style camera movement
- idle persistence for camera position, yaw, pitch, and FOV
- Added settings-page Godot camera controls with coalesced updates,
restart-safe session handling, and stale request protection.
- Kept scene input simple: Electron does not cache the selected model
for replay. Each Godot start receives the current model selection from
the renderer.
## File Guide
Shared contracts:
- `packages/stage-shared/src/godot-stage/view-state.ts` defines the
Godot view-state contract and schema validation.
- `packages/stage-shared/src/godot-stage/index.ts` exports the Godot
shared contract surface.
- `packages/stage-shared/package.json` exposes the new shared entry.
Electron / renderer bridge:
- `apps/stage-tamagotchi/src/shared/eventa/index.ts` adds the Eventa
contracts for Godot status, scene input, view snapshot, patch, and error
events.
- `apps/stage-tamagotchi/src/main/services/airi/godot-stage/index.ts`
owns the Godot sidecar lifecycle, local WebSocket bridge, scene input
forwarding, and view-state forwarding.
Settings page:
- `apps/stage-tamagotchi/src/renderer/pages/settings/models/index.vue`
wires the settings page to Godot status, scene input, snapshots, and
patches.
-
`apps/stage-tamagotchi/src/renderer/pages/settings/models/godot-view-patch-queue.ts`
coalesces high-frequency camera edits before sending them to Godot.
-
`apps/stage-tamagotchi/src/renderer/pages/settings/models/godot-view-session.ts`
tracks renderer-local Godot session epochs so stale async results are
ignored.
Shared settings UI:
-
`packages/stage-ui/src/components/scenarios/settings/model-settings/godot.vue`
renders the Godot camera controls.
-
`packages/stage-ui/src/components/scenarios/settings/model-settings/panel.vue`
routes the model settings panel between Live2D, VRM, and Godot settings.
-
`packages/stage-ui/src/components/scenarios/settings/model-settings/runtime.ts`
resolves model-settings runtime display state and Godot camera control
range.
- `packages/stage-ui/src/components/data-pane/property-number.vue`
updates number control behavior so config changes such as min/max/range
are reflected correctly.
Godot runtime:
- `engines/stage-tamagotchi-godot/scripts/StageRoot.cs` wires scene
loading, view runtime, and transport together.
- `engines/stage-tamagotchi-godot/scripts/scene/StageSceneController.cs`
loads VRM avatars and normalizes avatar facing direction.
- `engines/stage-tamagotchi-godot/scripts/view/StageViewRuntime.cs` owns
Godot view-state updates, snapshots, patch application, and idle
persistence.
-
`engines/stage-tamagotchi-godot/scripts/view/StageCameraPoseController.cs`
computes avatar bounds, bootstraps the camera, applies camera pose, and
handles camera movement math.
-
`engines/stage-tamagotchi-godot/scripts/view/StageCameraInputController.cs`
maps mouse and keyboard input into camera operations.
- `engines/stage-tamagotchi-godot/scripts/view/StageViewStateRules.cs`
centralizes view-state defaults and validation rules.
- `engines/stage-tamagotchi-godot/scripts/view/StageViewStateStore.cs`
persists and loads Godot camera view state.
- `engines/stage-tamagotchi-godot/scripts/transport/StageViewJson.cs`
parses and serializes view-state transport payloads.
-
`engines/stage-tamagotchi-godot/scripts/transport/StageViewPayloads.cs`
defines the C# payload records used by the transport layer.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
Adds the experimental Godot stage sidecar path for `stage-tamagotchi`.
This PR wires the existing Tamagotchi model selection flow into an
external Godot runtime window. The renderer gates Godot scene input to
VRM models, Electron main materialises the selected model bytes to a
local file, and the Godot sidecar receives the native path over a local
WebSocket bridge before importing and displaying the avatar at runtime.
## What Changed
- Added a typed Godot scene input contract with `format: "vrm"`.
- Added renderer-side VRM-only gating before sending selected model data
to Electron main.
- Added Electron main sidecar management for:
- launching Godot
- starting the local WebSocket bridge
- materialising selected VRM bytes under app `userData`
- forwarding scene apply messages to Godot
- optional remote debugging support
- Added Godot runtime scripts for:
- sidecar startup and WebSocket orchestration
- message envelope parsing
- avatar import and atomic replacement
- runtime VRM import through Godot `GLTFDocument`
- Added engine-local docs for runtime import, live debugging, vendor
patches, and current VRM support boundaries.
- Removed temporary tests after using them to verify the glue behaviour
locally, to keep the review surface smaller.
## Vendor Code Note
A large part of this PR is vendored Godot add-on code, not AIRI business
logic.
The bulk of the added files under:
- `engines/stage-tamagotchi-godot/addons/vrm/**`
- `engines/stage-tamagotchi-godot/addons/Godot-MToon-Shader/**`
comes from V-Sekai Godot VRM / MToon add-ons. These files are required
because Godot plugins are project-local source/assets rather than
package-manager dependencies.
The intended review scope for vendor code is limited to:
- source baseline metadata
- license/plugin config
- Godot-generated metadata notes
- the documented local patch in `addons/vrm/vrm_extension.gd`
The application/runtime code to review is mainly under:
- `apps/stage-tamagotchi/src/shared/eventa/index.ts`
- `apps/stage-tamagotchi/src/renderer/pages/settings/models/`
- `apps/stage-tamagotchi/src/main/services/airi/godot-stage/`
- `engines/stage-tamagotchi-godot/scripts/`
## Current Boundary
This is still an experimental G1 Godot sidecar path.
The runtime scene input contract accepts `.vrm` files only. The current
Godot runtime importer covers the VRM 0.x path used by the local fixture
through AIRI’s runtime bridge over the vendored VRM extension. VRM 1.0
editor import support exists in the vendored add-on, but the sidecar
runtime importer does not yet register the full `VRMC_*` extension set,
so this PR does not claim full VRM 1.0 runtime support.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
Add the G0 Godot Stage sidecar preview for `stage-tamagotchi`.
## Design
- Keep Electron as the desktop host and run Godot as a separate sidecar
window by design.
- Use the settings window as the entry point for starting/stopping the
experimental Godot Stage.
- Require explicit `GODOT4` in development mode instead of
auto-discovering local Godot installs.
- Use the packaged sidecar under `process.resourcesPath/godot-stage` in
the packaged runtime.
- Close the Godot WebSocket lifecycle channel on startup failure and
stage shutdown.
## Changes
- Add the Electron main-side Godot Stage lifecycle service.
- Add renderer/settings wiring for switching to the experimental Godot
Stage.
- Add the minimal Godot stage runtime skeleton and WebSocket handshake
path.
- Add Godot export presets for sidecar builds.
- Add sidecar path verification for the Godot export preset and
`electron-builder` resource contract.
- Document the development runtime setup and packaging expectations.
## CI/CD
- Align Godot CI to `4.6.2`.
- Add Linux Godot export smoke coverage as the fastest CI export path.
- Add sidecar contract verification to CI.
- Run packaged sidecar verification after `electron-builder --dir`.
CD is intentionally deferred in this PR. The release workflow still
needs a later step to export the Godot sidecar before packaging release
artefacts.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
