XCEngine/project/Assets/Characters/Nahida/DependencyMap.md

# Nahida Dependency Map

This document captures the Unity sample semantics that must survive the port.

Source roots:
- Unity reference project: `mvs/NahidaRender`
- Engine project staging area: `project/Assets/Characters/Nahida`

## Texture groups

Body and Dress1:
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Body_Diffuse.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Body_Lightmap.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Body_Normalmap.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Body_Shadow_Ramp.png`

Hair and Dress2:
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Hair_Diffuse.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Hair_Lightmap.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Hair_Normalmap.png`
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Hair_Shadow_Ramp.png`

Face and shared:
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Face_Diffuse.png`
- `Textures/Shared/Avatar_Loli_Tex_FaceLightmap.png`
- `Textures/Shared/Avatar_Tex_Face_Shadow.png`
- `Textures/Shared/Avatar_Tex_MetalMap.png`

Reference-only extra:
- `Textures/Nahida/Avatar_Loli_Catalyst_Nahida_Tex_Body_Specular_Ramp.png`
  - Present in the sample resources.
  - Not directly referenced by the seven Unity Nahida materials that were copied into `docs/reference/NahidaUnity/Materials`.

## Material graph

Shared base material:
- `docs/reference/NahidaUnity/Materials/Nahida_Base.mat`
  - Uses `docs/reference/NahidaUnity/Shaders/Genshin.shader`
  - Binds shared `_MetalMap = Textures/Shared/Avatar_Tex_MetalMap.png`
  - Carries shared shadow, rim, outline, and specular defaults

Body branch:
- `docs/reference/NahidaUnity/Materials/Nahida_Body.mat`
  - `_BaseMap = Body_Diffuse`
  - `_LightMap = Body_Lightmap`
  - `_NormalMap = Body_Normalmap`
  - `_ShadowRamp = Body_Shadow_Ramp`
  - Enables emission, normal map, rim, specular, and smooth normal

- `docs/reference/NahidaUnity/Materials/Nahida_Dress1.mat`
  - Reuses the same body texture group
  - Double-sided
  - Uses smooth normal

Hair branch:
- `docs/reference/NahidaUnity/Materials/Nahida_Hair.mat`
  - `_BaseMap = Hair_Diffuse`
  - `_LightMap = Hair_Lightmap`
  - `_NormalMap = Hair_Normalmap`
  - `_ShadowRamp = Hair_Shadow_Ramp`
  - Enables emission, normal map, rim, specular, and smooth normal

- `docs/reference/NahidaUnity/Materials/Nahida_Dress2.mat`
  - Reuses the same hair texture group
  - Double-sided

Face branch:
- `docs/reference/NahidaUnity/Materials/Nahida_Face.mat`
  - `_BaseMap = Face_Diffuse`
  - `_FaceLightMap = Avatar_Loli_Tex_FaceLightmap`
  - `_FaceShadow = Avatar_Tex_Face_Shadow`
  - `_ShadowRamp = Body_Shadow_Ramp`
  - Marks `_IsFace = 1`
  - Depends on runtime `_FaceDirection`

- `docs/reference/NahidaUnity/Materials/Nahida_Brow.mat`
  - Reuses the same face texture group
  - Uses a tint override through `_BaseColor`
  - Sets outline width to `0`

## Shader semantics

Core shader files:
- `docs/reference/NahidaUnity/Shaders/Genshin.shader`
- `docs/reference/NahidaUnity/Shaders/GenshinInput.hlsl`
- `docs/reference/NahidaUnity/Shaders/GenshinForwardPass.hlsl`
- `docs/reference/NahidaUnity/Shaders/GenshinOutlinePass.hlsl`

Important shader features to preserve:
- `_LightMap` driven shadow partitioning
- `_FaceLightMap + _FaceShadow + _FaceDirection` face shading path
- `_MetalMap` driven specular/metal response
- Rim light
- Separate outline pass
- `_UseSmoothNormal` switch for outline data path

## Scene semantics from Unity sample

Reference scene:
- `docs/reference/NahidaUnity/Scenes/SampleScene.unity`

Observed setup:
- Instantiates `Avatar_Loli_Catalyst_Nahida.fbx` as a prefab instance
- Renames the root object to `NahidaUnityModel`
- Uses `SkinnedMeshRenderer`, not a static `MeshFilter + MeshRenderer` setup
- Overrides one renderer mesh with `Meshes/Nahida_Body_Smooth.mesh`
- Assigns body renderer material slots in this order:
  - slot 0: `Nahida_Hair.mat`
  - slot 1: `Nahida_Body.mat`
  - slot 2: `Nahida_Dress1.mat`
  - slot 3: `Nahida_Dress2.mat`
- Additional renderers use:
  - `Nahida_Face.mat`
  - `Nahida_Brow.mat`
- One face-related renderer writes `BlendShapeWeights[0] = 100`

## Current static assembly baseline in XCEngine

Preview scene:
- `Assets/Scenes/NahidaPreview.xc`

Current static assembly uses the existing imported FBX sub-meshes from:
- `Assets/Models/nahida/Avatar_Loli_Catalyst_Nahida.fbx`

Scene-side material path mapping in `Assets/Scenes/NahidaPreview.xc`:
- `Nahida_Hair`
  - mesh localID: `5268898388415806497`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Hair.mat`
- `Nahida_Body`
  - mesh localID: `5268897288904178286`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Body.mat`
- `Nahida_Dress1`
  - mesh localID: `5268896189392550075`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Dress1.mat`
- `Nahida_Dress2`
  - mesh localID: `5268895089880921864`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Dress2.mat`
- `Nahida_Brow`
  - mesh localID: `15841426242793151682`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Brow.mat`
- `Nahida_EffectMesh`
  - mesh localID: `692846506840157104`
  - temporary fallback material: `builtin://materials/default-primitive`
- `Nahida_EyeStar`
  - mesh localID: `8234240765526303311`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Face.mat`
- `Nahida_Face`
  - mesh localID: `1306782875462705981`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Face.mat`
- `Nahida_FaceEye`
  - mesh localID: `977130118610429631`
  - engine material: `Assets/Characters/Nahida/Materials/Nahida_Face.mat`

Current engine-native shader and materials:
- Shader: `Assets/Shaders/XCCharacterToon.shader`
- Materials:
  - `Assets/Characters/Nahida/Materials/Nahida_Hair.mat`
  - `Assets/Characters/Nahida/Materials/Nahida_Body.mat`
  - `Assets/Characters/Nahida/Materials/Nahida_Dress1.mat`
  - `Assets/Characters/Nahida/Materials/Nahida_Dress2.mat`
  - `Assets/Characters/Nahida/Materials/Nahida_Face.mat`
  - `Assets/Characters/Nahida/Materials/Nahida_Brow.mat`

Current model material remap sidecars:
- `Assets/Models/nahida/Avatar_Loli_Catalyst_Nahida.fbx.materialmap`
- `Assets/Characters/Nahida/Model/Avatar_Loli_Catalyst_Nahida.fbx.materialmap`

Format:
- `meshLocalID=Assets/.../Material.mat`
- Multiple material slots can be provided with `|`

Current gaps:
- No dedicated outline pass yet.
- Face shading logic now matches the Unity-style forward path more closely, but `_FaceDirection` is still not driven at runtime.

## Runtime driver semantics

Runtime driver:
- `docs/reference/NahidaUnity/Scripts/MaterialUpdater.cs`

Behavior:
- Reads the head bone transform every frame
- Rotates the configured local head direction
- Writes `_FaceDirection` into every material on the configured face renderers

This means face shading is not static material data. The engine port needs a runtime material-parameter driver.

## Post-process reference

Reference files:
- `docs/reference/NahidaUnity/Shaders/URPGenshinPostProcess.shader`
- `docs/reference/NahidaUnity/Scripts/Rendering/`
- `docs/reference/NahidaUnity/URPSettings/`

These are kept only as semantic reference for a later phase. They should not be treated as engine-native runtime assets.