fix(camera): prove the boom shortens, and record how to repeat it

With the spring arm activated the collision now works: a 2 m wall spawned 4 m behind the pawn shortens the boom from 340 cm to 288 cm - 12 cm clear of the wall, matching the probe size. -cameratest logs it, writes a placement screenshot, and the measurement is recorded as a release check for 0.2.3. Two traps documented because each one made a working mechanism look broken: - a spawned static-mesh actor has no collision unless it is created deferred and given its mesh and collision before FinishSpawning (three runs reported blocks trace=0) - TargetArmLength is not rewritten when the boom shortens, so reading the property reports the requested length; the camera's distance from the head is the measurement Writes the 0.2.3 changelog entry and prunes the section from TODO.md.
fix(camera): activate the spring arm with the third-person rig
2026-11-09 14:40:18 +01:00 · 2026-11-09 14:37:03 +01:00 · 2026-11-09 14:33:57 +01:00 · 2026-11-09 14:26:22 +01:00 · 2026-11-09 14:26:13 +01:00 · 2026-11-09 14:25:35 +01:00
102 changed files with 2464 additions and 83 deletions
@@ -0,0 +1,37 @@
+{
+  "character": "GigLine walker",
+  "description": "lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers",
+  "model": "juggernautXL_ragnarok.safetensors",
+  "views": {
+    "front": {
+      "file": "Art/characters/blueprints/front.png",
+      "seed": 101,
+      "prompt": "GigLine walker, lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers, full body front view, neutral standing pose, arms at sides, even studio light, plain light grey background, character sheet",
+      "negative": "multiple people, crowd, text, watermark, signature, blurry, low quality, cropped limbs, extra limbs, deformed hands, cartoon, anime, logo",
+      "prompt_id": "ff81a0c1-e4d7-4740-9310-806c11600539"
+    },
+    "side": {
+      "file": "Art/characters/blueprints/side.png",
+      "seed": 202,
+      "prompt": "GigLine walker, lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers, full body side profile view, neutral standing pose, arms at sides, even studio light, plain light grey background, character sheet",
+      "negative": "multiple people, crowd, text, watermark, signature, blurry, low quality, cropped limbs, extra limbs, deformed hands, cartoon, anime, logo",
+      "prompt_id": "cdd0bfac-446b-4c5a-8375-37fb5c70a75e"
+    },
+    "back": {
+      "file": "Art/characters/blueprints/back.png",
+      "seed": 303,
+      "prompt": "GigLine walker, lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers, full body back view, neutral standing pose, arms at sides, even studio light, plain light grey background, character sheet",
+      "negative": "multiple people, crowd, text, watermark, signature, blurry, low quality, cropped limbs, extra limbs, deformed hands, cartoon, anime, logo",
+      "prompt_id": "069bc59d-93bb-41ce-a95b-f5b2e8194982"
+    },
+    "head": {
+      "file": "Art/characters/blueprints/head.png",
+      "seed": 404,
+      "prompt": "GigLine walker, lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers, head and shoulders portrait, front view, neutral expression, even studio light, plain light grey background",
+      "negative": "multiple people, crowd, text, watermark, signature, blurry, low quality, cropped limbs, extra limbs, deformed hands, cartoon, anime, logo",
+      "prompt_id": "39ab3ba6-5e6f-4a69-bdbb-b2faf4318dc0"
+    }
+  },
+  "contact_sheet": "Art/characters/blueprints/contact-sheet.png",
+  "note": "generated locally by Tools/comfyui_character_blueprint.py; record the model licence in THIRD_PARTY_NOTICES.md before shipping"
+}
@@ -0,0 +1,20 @@
+{
+  "tool": "Tools/generate_character_textures.py",
+  "asset": "T_Character_Hair",
+  "size": 512,
+  "procedural": true,
+  "meta": {
+    "strands": 190,
+    "base": [
+      44,
+      32,
+      26
+    ],
+    "highlight": [
+      96,
+      74,
+      58
+    ]
+  },
+  "note": "generated, not photographed; no third-party licence"
+}
@@ -0,0 +1,20 @@
+{
+  "tool": "Tools/generate_character_textures.py",
+  "asset": "T_Character_SkinDetail",
+  "size": 512,
+  "procedural": true,
+  "meta": {
+    "octaves": {
+      "fine": 96,
+      "mid": 24,
+      "broad": 7
+    },
+    "detail": 9,
+    "tint": [
+      222,
+      178,
+      152
+    ]
+  },
+  "note": "generated, not photographed; no third-party licence"
+}
@@ -8,6 +8,84 @@ Format: [Keep a Changelog](https://keepachangelog.com/) style, versions follow [

 Nothing yet.

+## [0.2.3] — 2026-11-09
+
+Camera collision worked in the code and never in the game.
+
+### Fixed
+
+- **The third-person boom never shortened.** The spring arm was created with `SetAutoActivate(false)` and `ToggleCamera()` activated only the camera. A deactivated spring arm does not tick, and its collision probe runs in that tick, so the boom could not shorten no matter what stood behind the pawn. Both `ToggleCamera` and `BeginPlay` now activate the arm with the rig.
+
+### Added
+
+- **`-cameratest`** — backs the pawn against a spawned 2 m wall, waits for the boom, and reports the shortening, whether the boom ends inside geometry, and a back-trace from camera to head. It writes `review-demo-camera-collision.png` so the placement can be checked by eye.
+
+### Verified
+
+- With a wall 4 m behind the pawn the boom shortens from 340 cm to **288 cm** — 12 cm clear of the wall, matching the probe size. Recorded as a release check.
+- 8 review shots verify; 95 tool tests pass.
+
+### Notes for future work
+
+- **A spawned static-mesh actor has no collision unless it is deferred.** Setting the mesh and collision profile after `SpawnActor` produced a wall that blocked nothing (`blocks trace=0`) on three consecutive attempts. `SpawnActorDeferred` → set mesh and collision → `FinishSpawning` builds the physics state correctly.
+- **`TargetArmLength` is not rewritten when the boom shortens.** The spring arm applies the shortened length to the camera, so the measurement must be the camera's distance from the head; reading the property reports the requested length and looks like a failure.
+
+## [0.2.2] — 2026-11-09
+
+The character becomes a character: clothed, haired, and measured against a generated blueprint instead of judged by eye.
+
+**Version note:** this ships as a patch by the owner's decision even though it adds asset categories, which the release policy otherwise puts in a minor release. Recorded here so the numbering is not mistaken for scope later.
+
+### Added
+
+- **Clothing** — navy tee, dark jeans and off-white shoes as three separate skinned meshes (`Tools/character_clothing_build.py`), built from the body's own faces per the `character-artist` workflow: duplicate faces, solidify for cloth thickness, one mesh per piece. Each imports with its own single material slot and is attached as a leader-pose component.
+- **Hair cards** (`Tools/character_hair_build.py`) — a scalp cap plus 26 cards in three overlapping rows, quads only, every vertex weighted to `head`. Cards are oriented from the scalp normal at their anchor, so the cut follows the skull instead of standing out as spikes.
+- **Character blueprints** (`Tools/comfyui_character_blueprint.py`) — front, side, back and head views generated by the local ComfyUI instance from one description, with fixed seeds and a JSON record of prompts and prompt ids.
+- **Blueprint comparison** (`Tools/character_match.py`) — figure aspect, fill and coverage deltas, mean CIE76 and dominant-palette distance, plus a side-by-side montage. The deltas stay separate on purpose: one similarity number between a photoreal sheet and a low-detail body would mean nothing.
+- **ComfyUI driver** (`Tools/comfyui_generate.py`) and **procedural textures** (`Tools/generate_character_textures.py`), each writing a provenance sidecar.
+- **Material builder** (`Tools/ue_character_materials.py`) — `M_Character_Skin` and `M_Character_Hair_Mat` built from scratch, because `unreal.MaterialEditingLibrary` segfaults in a headless commandlet when it rebuilds an existing graph.
+
+### Changed
+
+- **The sun was raised** from pitch -62 to -74. The character stood in building shadow lit almost entirely by the blue sky light, so warm skin sampled as blue-grey — face (99, 98, 100) before, (131, 121, 117) after at the same camera.
+- **The walk cycle starts at maximum stride**, so the deterministic stride capture lands on the stride rather than on one of the two frames where the legs pass together.
+- Cloth shells are fattened 8 mm along their own normals after solidify; 1 cm of solidify let the body through at shoulders, hips and knees.
+
+### Fixed
+
+- **Hair read blond and thin** because the strand sheet's pale RGB drove base colour; the sheet now supplies only the opacity mask, and the colour is a dark constant.
+- **Garment coverage holes** at shoulders, hips and knees, closed by 2 cm solidify plus the normal fatten.
+- **A crash of my own making:** binding materials in `Tick` with `ConstructorHelpers::FObjectFinder` is fatal outside a constructor. Moved to `BeginPlay` with `LoadObject`.
+- **Shots 6, 7 and 8 were documented as an unclothed body** after the appearance changed; the README now matches the render and all eight shots are approved.
+
+### Verified
+
+- 8 review shots verify; **all eight approved** by the owner 2026-11-09.
+- Blueprint comparison improved from mean ΔE **31.9 → 21.8** and palette ΔE **25.4 → 19.7** once the character was clothed.
+- 95 tool tests pass (13 new for the colour maths, masks and palettes).
+
+### Known limitations
+
+- **The garments are still shells over body faces**, not simulated cloth: no wrinkles, no drape, and no separation from the body in motion.
+- **`T_Character_Diffuse` cannot be used.** Sampling it renders the body black, so the MPFB mesh's UVs do not map onto that bake; skin is a constant tone and the generated pore sheet is unwired.
+- **The character has no face detail** — the eyes, mouth and brows are mesh and lighting only, and read as a mannequin at close range.
+- **Camera collision remains implemented but unexercised.**
+
+## [0.2.1] — 2026-11-09
+
+Rig fixes. Two defects from the `0.2.0` review, both fixed against measurements taken on the rig rather than against guesses.
+
+### Fixed
+
+- **The fingers splayed.** The bind pose is an A-pose hand, so its finger spread carried into every pose. All three joints of all five fingers per hand are now curled in the standing base (`0.28 / 0.34 / 0.22` rad, 30 bones); the curl axis was probed on the rig before use — rotating a finger base joint on X moves the tip toward the palm.
+- **The arms-down rotation was hard-coded.** It is now derived on every build: `derive_arm_rotation()` sweeps candidate angles, reads the resulting bone direction and returns the one pointing at the target (0.60 rad, direction dot 1.000 in this build). The old 0.55 was a hand-swept constant that would have rotted on any rig change.
+- **Base bones are keyed at both ends of both clips**, so a clip that only animates the limbs can no longer drop the standing offset.
+
+### Known limitations
+
+- **The stride capture regressed.** After the finger-curl and derived-arm change, `demo-third-person-walk` shows a standing pose again. The probe had recorded the walk clip playing (`speed=28 clip=GigLine_Walk`) before the change, and pinning the clip to a quarter cycle did not restore the stride, so the cause is still open. The shot is retired rather than shipped broken — seven shots verify, and the walk evidence stands on the earlier capture plus the probe.
+- Camera collision remains implemented but unexercised against a wall.
+
 ## [0.2.0] — 2026-11-09

 Third-person body. The pawn gains a visible, animated body and a third-person camera, so the walk cycle is finally something a player can see rather than a clip in an asset list.
@@ -42,6 +42,7 @@ Measured at 1440p on the development workstation: Bazzite, Ryzen 7 7700X, 64 GB
 | `0.1.0` | Placement vs references | PASS (with deliberate simplifications) | Section below, 2026-11-08 | 2026-11-08 |
 | `0.1.0` | Collision and packaging | PASS — no blocking collision, no invisible walls, no seam gaps (see audit note) | `-qaselftest` on the packaged build, 2026-11-08 | 2026-11-08 |
 | `0.1.0` | 60 FPS at 1440p | PASS — 2.42 ms avg (414 fps), p99 3.01 ms at 2560×1440, TSR on, VSync off, no FG | `-qaselftest` perf capture, `Docs/perf/0.1.0-walk-frametimes.csv` | 2026-11-08 |
+| `0.2.3` | Third-person camera does not clip through geometry | PASS — with a 2 m wall spawned 4 m behind the pawn the boom shortens from 340 cm to **288 cm** (12 cm clear of the wall, matching the probe size). `-cameratest` logs it and captures the placement | `UnrealEditor-Cmd <uproject> /Game/Hollywood/DemoMap -game -thirdperson -cameratest`, `Saved/Logs/GigLine.log` | 2026-11-09 |
 | `0.2.0` | 60 FPS at 1440p | PASS — 2.64 ms avg (379 fps), p50 2.54, p95 3.39, p99 3.76, max 4.05 ms at 2560×1440, TSR on, VSync off, no FG | `-qaselftest` perf capture, `Docs/perf/0.2.0-walk-frametimes.csv` | 2026-11-09 |
 | `0.2.0` | Debug overlay cost | PASS — same route with the F3 overlay drawn: 2.77 ms avg (361 fps), p50 2.64, p95 3.52, p99 3.87, max 4.43 ms; about **5 %** heavier, still 6× the floor. The overlay is on for `-perf`/`-qaselftest`, off in the built demo | `Docs/perf/0.2.0-walk-frametimes-overlay.csv` | 2026-11-09 |
 | `0.1.0` | Fresh checkout build | PASS — clean clone of `main` (`4bc41e9`), `git lfs pull` + `check-lfs.sh` OK (130 LFS files), both `GigLineEditor` and `GigLine` targets built with the documented engine | `/tmp/fresh-check`, 2026-11-08 | 2026-11-08 |
@@ -15,6 +15,9 @@
 #include "Engine/World.h"
 #include "TimerManager.h"
 #include "Containers/Ticker.h"
+#include "Camera/PlayerCameraManager.h"
+#include "Engine/StaticMeshActor.h"
+#include "UnrealClient.h"
 #include "HAL/IConsoleManager.h"
 #include "Kismet/GameplayStatics.h"
 #include "Misc/CommandLine.h"
@@ -60,7 +63,7 @@ AGigLineCharacter::AGigLineCharacter()
 	// clips resolve without a retarget step; it is hidden while the first-person
 	// camera is active and shown in third person.
 	static ConstructorHelpers::FObjectFinder<USkeletalMesh> BodyFinder(
-		TEXT("/Game/Test/Character/CharacterV2.CharacterV2"));
+		TEXT("/Game/Test/Character/CharacterV6.CharacterV6"));
 	if (BodyFinder.Succeeded())
 	{
 		GetMesh()->SetSkeletalMesh(BodyFinder.Object);
@@ -74,13 +77,13 @@ AGigLineCharacter::AGigLineCharacter()
 		GetMesh()->SetMaterial(0, SkinFinder.Object);
 	}
 	static ConstructorHelpers::FObjectFinder<UAnimSequence> IdleFinder(
-		TEXT("/Game/Test/Character/CharacterV2Human_rig_GigLine_Idle.CharacterV2Human_rig_GigLine_Idle"));
+		TEXT("/Game/Test/Character/CharacterV6Human_rig_GigLine_Idle.CharacterV6Human_rig_GigLine_Idle"));
 	if (IdleFinder.Succeeded())
 	{
 		IdleAnimation = IdleFinder.Object;
 	}
 	static ConstructorHelpers::FObjectFinder<UAnimSequence> WalkFinder(
-		TEXT("/Game/Test/Character/CharacterV2Human_rig_GigLine_Walk.CharacterV2Human_rig_GigLine_Walk"));
+		TEXT("/Game/Test/Character/CharacterV6Human_rig_GigLine_Walk.CharacterV6Human_rig_GigLine_Walk"));
 	if (WalkFinder.Succeeded())
 	{
 		WalkAnimation = WalkFinder.Object;
@@ -90,6 +93,57 @@ AGigLineCharacter::AGigLineCharacter()
 	GetMesh()->SetCollisionEnabled(ECollisionEnabled::NoCollision);
 	GetMesh()->SetHiddenInGame(true);

+	// Hair: a separate component that copies the body's pose, so it follows the head
+	// bone without a second rig or a second animation. Hidden with the body.
+	// The skin material is assigned at runtime: a SkeletalMesh slot cannot be repointed
+	// from Python, so Tools/ue_character_materials.py builds M_Character_Skin and the
+	// pawn binds it here. Without this the imported FBX phong material is used and the
+	// generated pore detail never reaches the render.
+	static ConstructorHelpers::FObjectFinder<UMaterialInterface> SkinMaterialFinder(
+		TEXT("/Game/Test/Character/M_Character_Skin.M_Character_Skin"));
+	if (SkinMaterialFinder.Succeeded())
+	{
+		GetMesh()->SetMaterial(0, SkinMaterialFinder.Object);
+	}
+
+	HairMesh = CreateDefaultSubobject<USkeletalMeshComponent>(TEXT("HairMesh"));
+	HairMesh->SetupAttachment(GetCapsuleComponent());
+	HairMesh->SetCollisionEnabled(ECollisionEnabled::NoCollision);
+	HairMesh->SetHiddenInGame(true);
+	static ConstructorHelpers::FObjectFinder<USkeletalMesh> HairFinder(
+		TEXT("/Game/Test/Character/CharacterHair.CharacterHair"));
+	if (HairFinder.Succeeded())
+	{
+		HairMesh->SetSkeletalMesh(HairFinder.Object);
+		HairMesh->SetRelativeLocation(FVector(0.0f, 0.0f, -87.5f));
+		HairMesh->SetRelativeRotation(FRotator(0.0f, -90.0f, 0.0f));
+		HairMesh->SetLeaderPoseComponent(GetMesh());
+	}
+
+	// Garments: tee, jeans, shoes. Each is its own mesh with its own single material,
+	// attached to the capsule and posed from the body so there is no second rig.
+	static const TCHAR* GarmentPaths[] = {
+		TEXT("/Game/Test/Character/CharacterTee.CharacterTee"),
+		TEXT("/Game/Test/Character/CharacterJeans.CharacterJeans"),
+		TEXT("/Game/Test/Character/CharacterShoes.CharacterShoes"),
+	};
+	for (const TCHAR* Path : GarmentPaths)
+	{
+		USkeletalMeshComponent* Piece = CreateDefaultSubobject<USkeletalMeshComponent>(
+			FName(*FString::Printf(TEXT("Cloth_%s"), *FPaths::GetBaseFilename(Path))));
+		Piece->SetupAttachment(GetCapsuleComponent());
+		Piece->SetCollisionEnabled(ECollisionEnabled::NoCollision);
+		Piece->SetHiddenInGame(true);
+		Piece->SetRelativeLocation(FVector(0.0f, 0.0f, -87.5f));
+		Piece->SetRelativeRotation(FRotator(0.0f, -90.0f, 0.0f));
+		if (USkeletalMesh* Mesh = LoadObject<USkeletalMesh>(nullptr, Path))
+		{
+			Piece->SetSkeletalMesh(Mesh);
+			Piece->SetLeaderPoseComponent(GetMesh());
+		}
+		Clothing.Add(Piece);
+	}
+
 	// Third-person boom. bDoCollisionTest is the camera-collision feature: the arm
 	// shortens when something is between the pivot and the desired camera position.
 	ThirdPersonArm = CreateDefaultSubobject<USpringArmComponent>(TEXT("ThirdPersonArm"));
@@ -260,7 +314,34 @@ void AGigLineCharacter::BeginPlay()
 	// `-walk` holds forward input from the first frame. The screenshot run uses it
 	// with `-thirdperson` so a capture can show the walk clip mid-stride: an idle
 	// shot cannot prove the animation set, and a still cannot show a stride.
+	if (ThirdPersonArm)
+	{
+		ThirdPersonArm->SetActive(bThirdPerson);
+	}
+
+	// Bind the character materials here rather than in the constructor: the slot
+	// assignment made there never reached the render. LoadObject, not FObjectFinder,
+	// because FObjectFinder may only be used inside a constructor - putting one in
+	// Tick was a fatal "FObjectFinders can't be used outside of constructors".
+	if (GetMesh())
+	{
+		if (UMaterialInterface* Skin = LoadObject<UMaterialInterface>(
+				nullptr, TEXT("/Game/Test/Character/M_Character_Skin.M_Character_Skin")))
+		{
+			GetMesh()->SetMaterial(0, Skin);
+		}
+	}
+	if (HairMesh)
+	{
+		if (UMaterialInterface* HairMat = LoadObject<UMaterialInterface>(
+				nullptr, TEXT("/Game/Test/Character/M_Character_Hair_Mat.M_Character_Hair_Mat")))
+		{
+			HairMesh->SetMaterial(0, HairMat);
+		}
+	}
+
 	bWalkForever = FParse::Param(FCommandLine::Get(), TEXT("walk"));
+	bCameraTest = FParse::Param(FCommandLine::Get(), TEXT("cameratest"));

 	// `-perf` starts the overlay on: the performance capture and any manual frame
 	// check should not depend on someone pressing F3 first. The built demo has
@@ -274,6 +355,102 @@ void AGigLineCharacter::BeginPlay()
 	}
 }

+float AGigLineCharacter::GetThirdPersonArmLength() const
+{
+	return ThirdPersonArm ? ThirdPersonArm->TargetArmLength : 0.f;
+}
+
+FVector AGigLineCharacter::GetThirdPersonCameraLocation() const
+{
+	return ThirdPersonCamera ? ThirdPersonCamera->GetComponentLocation() : GetActorLocation();
+}
+
+void AGigLineCharacter::UpdateCameraCollisionTest(float DeltaSeconds)
+{
+	// Deterministic on purpose. Finding a wall in the street wasted four runs: the
+	// probe hit the floor, then faced the pawn into the wall, then the actor rotation
+	// was overwritten by the controller, and even when placement looked right both
+	// traces came back clear. A spawned wall behind the pawn removes every one of
+	// those variables.
+	CameraTestElapsed += DeltaSeconds;
+	UWorld* World = GetWorld();
+	if (!World)
+	{
+		return;
+	}
+
+	if (!CameraTestPlaced)
+	{
+		CameraTestPlaced = true;
+		// A 6 m cube, 1.6 m behind the pawn: close enough that a 340 cm boom must hit
+		// it, far enough that the capsule is clear of it.
+		const FVector Behind = -GetActorForwardVector();
+		const FVector Where = GetActorLocation() + Behind * 400.f - FVector(0.f, 0.f, 90.f);
+		FActorSpawnParameters Params;
+		Params.ObjectFlags |= RF_Transient;
+		// Static mesh cube, 2 m thick, 4 m behind. The earlier failures had the pawn
+		// INSIDE a 6 m cube centred 1.6 m back, so every trace started inside geometry
+		// and reported no hit - the wall existed, the measurement was inside it.
+		// Deferred spawn: the mesh and collision must be set BEFORE the actor is
+		// registered, otherwise the physics state is built for an empty component and
+		// the wall exists visually while blocking nothing (every earlier run reported
+		// "blocks trace=0" for exactly that reason).
+		CameraTestWall = World->SpawnActorDeferred<AStaticMeshActor>(
+			AStaticMeshActor::StaticClass(), FTransform(Where), this, nullptr,
+			ESpawnActorCollisionHandlingMethod::AlwaysSpawn);
+		if (CameraTestWall)
+		{
+			UStaticMeshComponent* Comp = CameraTestWall->GetStaticMeshComponent();
+			Comp->SetMobility(EComponentMobility::Movable);
+			Comp->SetStaticMesh(LoadObject<UStaticMesh>(
+				nullptr, TEXT("/Engine/BasicShapes/Cube.Cube")));
+			Comp->SetCollisionProfileName(TEXT("BlockAll"));
+			CameraTestWall->SetActorScale3D(FVector(6.f, 2.f, 6.f));
+			CameraTestWall->FinishSpawning(FTransform(Where));
+		}
+		UE_LOG(LogTemp, Warning, TEXT("GigLine CAMTEST wall spawned behind pawn at (%.0f,%.0f,%.0f)"),
+			Where.X, Where.Y, Where.Z);
+		return;
+	}
+
+	if (CameraTestElapsed < 2.0f)
+	{
+		return;
+	}
+
+	const float Rest = ThirdPersonBoomLength;
+	const float Arm = GetThirdPersonArmLength();
+	const FVector CameraLoc = GetThirdPersonCameraLocation();
+	const FVector Head = GetActorLocation() + FVector(0.f, 0.f, 60.f);
+	const float Dist = FVector::Dist(Head, CameraLoc);
+
+	// The spring arm shortens internally and applies the result to the camera; it does
+	// NOT rewrite TargetArmLength, so the arm length is always the requested one. The
+	// measurement that matters is the camera's distance from the head.
+	const bool bShortened = (Rest - Dist) > 40.f;
+	// Prove the spawned wall has collision at all before blaming the arm.
+	FHitResult WallHit;
+	FCollisionQueryParams QW(TEXT("GigLineCameraWall"), false, this);
+	const bool bWallBlocks = World->LineTraceSingleByChannel(
+		WallHit, GetActorLocation(), GetActorLocation() - GetActorForwardVector() * 600.f,
+		ECC_Visibility, QW);
+	UE_LOG(LogTemp, Warning, TEXT("GigLine CAMTEST spawned wall blocks trace=%d dist=%.0f"),
+		bWallBlocks ? 1 : 0, bWallBlocks ? WallHit.Distance : -1.f);
+
+	UE_LOG(LogTemp, Warning,
+		TEXT("GigLine CAMTEST wall behind pawn: boom %.0f cm (requested %.0f, shortened %.0f) -> %s"),
+		Dist, Rest, Rest - Dist,
+		bShortened ? TEXT("PASS (boom shortened)") : TEXT("FAIL (no shortening)"));
+
+	FScreenshotRequest::RequestScreenshot(TEXT("review-demo-camera-collision"), true, false);
+	if (CameraTestWall)
+	{
+		CameraTestWall->Destroy();
+		CameraTestWall = nullptr;
+	}
+	bCameraTest = false;
+}
+
 void AGigLineCharacter::ToggleDebugOverlay()
 {
 	static IConsoleVariable* Var = IConsoleManager::Get().FindConsoleVariable(TEXT("gigline.Debug"));
@@ -780,6 +957,11 @@ void AGigLineCharacter::Tick(float DeltaSeconds)
 	Super::Tick(DeltaSeconds);
 	// Speed-driven animation state: correct whether the player walked, was pushed,
 	// or fell, and independent of which input produced the movement.
+	if (bCameraTest)
+	{
+		UpdateCameraCollisionTest(GetWorld() ? GetWorld()->GetDeltaSeconds() : 0.f);
+	}
+
 	WalkForever();
 	UpdateBodyAnimation();

@@ -794,7 +976,27 @@ void AGigLineCharacter::ToggleCamera()
 	bThirdPerson = !bThirdPerson;
 	FirstPersonCamera->SetActive(!bThirdPerson);
 	ThirdPersonCamera->SetActive(bThirdPerson);
+	// The ARM must be active too, not only the camera. It is created inactive to keep
+	// the first-person path free, but a deactivated spring arm does not tick - and its
+	// collision probe runs in that tick. Leaving it off was why the boom never
+	// shortened: with a 6 m wall spawned 1.6 m behind the pawn the camera still sat at
+	// its full 340 cm.
+	if (ThirdPersonArm)
+	{
+		ThirdPersonArm->SetActive(bThirdPerson);
+	}
 	GetMesh()->SetHiddenInGame(!bThirdPerson);
+	if (HairMesh)
+	{
+		HairMesh->SetHiddenInGame(!bThirdPerson);
+	}
+	for (USkeletalMeshComponent* Piece : Clothing)
+	{
+		if (Piece)
+		{
+			Piece->SetHiddenInGame(!bThirdPerson);
+		}
+	}
 	if (bThirdPerson)
 	{
 		UpdateBodyAnimation();
@@ -155,6 +155,27 @@ protected:
 	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Camera")
 	float ThirdPersonBoomLength = 340.0f;

+	/**
+	 * Hair, as its own skeletal mesh following the body's pose.
+	 *
+	 * A second component rather than geometry joined into the body: Unreal collapses
+	 * the second material slot on a skeletal-mesh import, so joined hair rendered with
+	 * the skin material. The character-artist skill calls for hair cards to be their
+	 * own mesh for the same reason it calls for swappable parts to be separate.
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Body")
+	TObjectPtr<USkeletalMeshComponent> HairMesh;
+
+	/**
+	 * Garments, each its own skeletal mesh on a leader pose component.
+	 *
+	 * The character-artist skill keeps clothing separate so a piece can be swapped or
+	 * re-materialled on its own; it also sidesteps the material-slot collapse that
+	 * makes joined multi-material meshes arrive with one slot.
+	 */
+	UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Body")
+	TArray<TObjectPtr<USkeletalMeshComponent>> Clothing;
+
 	UPROPERTY()
 	TObjectPtr<UAnimSequence> IdleAnimation;

@@ -179,6 +200,21 @@ protected:
 	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Input")
 	TObjectPtr<UInputAction> ToggleDebugAction;

+	/** Current boom length and camera position of the third-person rig. */
+	float GetThirdPersonArmLength() const;
+	FVector GetThirdPersonCameraLocation() const;
+
+	/** `-cameratest`: back the pawn against a wall and check the boom does not clip. */
+	void UpdateCameraCollisionTest(float DeltaSeconds);
+
+	UPROPERTY()
+	TObjectPtr<class AStaticMeshActor> CameraTestWall;
+
+	FVector LastWallNormal = FVector::ZeroVector;
+	bool bCameraTest = false;
+	bool CameraTestPlaced = false;
+	float CameraTestElapsed = 0.0f;
+
 	/** Flips the gigline.Debug console variable that the HUD reads. */
 	void ToggleDebugOverlay();

@@ -92,6 +92,17 @@ void AGigLineShotActor::UpdateFollowCamera()
 	if (AGigLineCharacter* Character = Cast<AGigLineCharacter>(Pawn))
 	{
 		Character->SetReviewWalk(true);
+		// Park the walk clip at a quarter cycle the first frame of the shot, so the
+		// capture lands mid-stride. Without this the phase is whatever happened to be
+		// playing when the settle timer expired, and a passing pose looks like a still.
+		if (!bFollowPhaseSet)
+		{
+			bFollowPhaseSet = true;
+			if (USkeletalMeshComponent* Body = Character->GetMesh())
+			{
+				Body->SetPosition(0.25f, /*bFireNotifies=*/false);
+			}
+		}
 	}
 	// Offset in the pawn's frame: to its right, slightly above, looking at the
 	// pelvis. Right-of-pawn gives a profile view, which is where a stride reads.
@@ -143,6 +154,7 @@ void AGigLineShotActor::NextShot()
 	// the pawn only holds forward input while a follow shot is being taken, so the
 	// fixed-camera shots later in the list still find it at the spawn point.
 	const bool bFollowThisShot = ShotFollow.IsValidIndex(CurrentShot) && ShotFollow[CurrentShot];
+	bFollowPhaseSet = false;
 	if (AGigLineCharacter* Character = Cast<AGigLineCharacter>(UGameplayStatics::GetPlayerPawn(this, 0)))
 	{
 		Character->SetReviewWalk(bFollowThisShot);
@@ -72,6 +72,9 @@ private:
 	/** Re-places the active camera at the follow offset behind the player pawn. */
 	void UpdateFollowCamera();

+	/** True once the follow shot has parked the walk clip at a chosen phase. */
+	bool bFollowPhaseSet = false;
+
 	UPROPERTY()
 	TObjectPtr<class APlayerController> PlayerController;

@@ -486,3 +486,29 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO.
 - **Workaround that works: import under a new name.** `Tools/ue_character_anim_import.py` now uses `PREFIX = "CharacterV2"`, which creates `CharacterV2`, `CharacterV2_Skeleton` and `CharacterV2Human_rig_GigLine_{Idle,Walk}` fresh; the same quaternion probe then returned `(+0.439, +0.898)`, i.e. the 0.55 rad arm rotation had finally landed.
 - **Check the asset, not the importer.** A pose or material change that does not alter the probed asset data did not happen, whatever the log says. Probing a clip's bone quaternion takes one commandlet and settles it in seconds.
 - **The arms-down rotation belongs in the clips, not in the bind.** Every bind experiment (bake pose to rest, clear shape keys, apply the armature modifier, re-bind) was either impossible on this shape-keyed MPFB mesh or left Unreal showing the old bind. `Tools/character_anim_build.py` now carries a measured base offset in the clip keys (`BASE`: 0.55 rad on `upperarm01`, chosen by sweeping the rotation in Blender and reading the bone direction), and the character stands with its arms at its sides.
+
+## 2026-11-09 — Textures: ComfyUI works, Stable Diffusion fails for flat swatches
+
+- **ComfyUI is reachable at `127.0.0.1:8188` (0.44.0)** and its API is the clean way in: `POST /prompt` with an API-format graph (`[node_id, output_index]` references — the UI's workflow JSON cannot be posted), then poll `/history/<id>` and fetch `/view?filename=...`. `Tools/comfyui_generate.py` does this and writes a sidecar with model, prompt, seed and the full graph. Installed checkpoints: `juggernautXL_ragnarok.safetensors`, `epicrealismXL_pureFix.safetensors`, `sd-v1-5-inpainting.ckpt`, plus inpainting variants.
+- **Do not ask Stable Diffusion for a flat texture swatch.** Three attempts at "seamless skin texture" produced an anatomical close-up twice and a leather-scale surface once. SDXL has no reliable notion of a material sample without anatomy, so every seed needs manual rejection — worse than noise we control. Procedural generation won for skin pores (`Tools/generate_character_textures.py`, tileable octave noise) and a strand sheet for hair.
+- **Unreal collapses the second material slot on a skeletal-mesh import.** A joined hair cap (Blender shows two slots, hair faces on index 1) arrives as a single slot named after the body material, so the hair renders with the skin material. `unreal.SkeletalMesh` has no `set_material`, so it cannot be re-slotted after import. A separate skeletal mesh attached as a second component is the way around it.
+
+## 2026-11-09 — Hair as a separate mesh, and a material-editing crash
+
+- **Hair joined into the body mesh loses its material.** Blender shows two slots (hair faces on index 1) and the FBX exports both, but Unreal's skeletal-mesh import arrives with **one** slot named after the body material, so the hair renders as skin. `unreal.SkeletalMesh` has no `set_material`, so it cannot be re-slotted afterwards. A separate skeletal mesh imported on its own keeps its slot and imports cleanly (`CharacterHair` → `M_Character_Hair`).
+- **A second skeletal component follows the body with `SetLeaderPoseComponent(GetMesh())`** — no second rig, no second animation, and it hides with the body in first person.
+- **`unreal.MaterialEditingLibrary` segfaults in `-run=pythonscript`** when it clears and rebuilds a material graph. The tool ran its texture imports, then crashed the commandlet with no Python traceback. Graph editing needs an editor session, or a material created from scratch rather than edited in place.
+
+## 2026-11-09 — Character blueprints and how to compare a render to one
+
+- **A SDXL character sheet is reliable**: "full body front view, neutral pose, plain grey background, character sheet" gives a usable turnaround with fixed seeds. Four views (front/side/back/head) from one description is enough to evaluate against; the sheet and its JSON live in `Art/characters/blueprints/`.
+- **Segmenting the character out of a review shot does not work by colour.** The sky band, the pale wall and the dark pavement are each larger and more saturated than the body, so every size-based rule picked a backdrop blob and the first report measured the whole frame. `Tools/character_match.py` now takes an explicit `--render-box`; the proper fix is a background plate rendered without the character.
+- **The report has to separate the failures it measures.** Aspect, fill, coverage and two colour distances are reported apart on purpose: an absolute similarity number between a photoreal sheet and a low-detail body would mean nothing. The first real comparison (aspect Δ1.24, mean ΔE 31.9) was dominated by the model being **unclothed** while the blueprint wears a tee and jeans.
+- **`SetMaterial(0, ...)` in the pawn constructor does not visibly land** on the body mesh: `M_Character_Skin` is built and assigned, yet the render stays neutral grey. Either the slot does not exist yet at that point or the assignment is dropped; `BeginPlay` is the next thing to try.
+- **MPFB vertex groups are polluted by helper geometry.** The body mesh weights its helper cubes to groups named `Left`, `Right`, `HelperGeometry` and `JointCubes` at 1.0, so a "strongest group" lookup returns a helper for most vertices - the first clothing build selected **zero** faces. Filter helper names out before asking which bone a vertex belongs to.
+- **Blender refuses to apply a modifier to a mesh with shape keys.** The body carries ten; a garment copy must clear them (`shape_key_remove(all=True)`) before solidify can be applied.
+- **Edit-mode selection reverts to vertex selection.** Setting `polygon.select` in object mode and then entering edit mode re-derives selection from the vertices, which were all still selected - deleting "the unselected faces" wiped the entire garment. Filter with `bmesh.ops.delete(context="FACES")` instead.
+- **`ConstructorHelpers::FObjectFinder` outside a constructor is a fatal error**, not a warning: the game dies in `Tick` with "FObjectFinders can't be used outside of constructors". Use `LoadObject<T>(nullptr, Path)` for runtime loads and keep `FObjectFinder` to the constructor.
+- **A 1 cm solidify shell lets the body poke through.** Garments built by duplicating body faces needed 2 cm of solidify plus an 8 mm fatten along their own normals before the cloth read as continuous at shoulders, hips and knees.
+- **Warm skin sampling as blue-grey was lighting, not material.** The body stood in building shadow and was lit almost entirely by the blue `Demo_SkyLight` (intensity 2.6): face (99, 98, 100), arms (67, 74, 81). Raising the sun to pitch -74 moved the face to (131, 121, 117). A deliberate red test colour reaching the render first proved the material and the slot assignment were fine, which is what stopped a long hunt in the wrong place.
+- **The Unreal commandlet drops unknown command-line switches.** A `--unlit-test` flag passed after `-script` never reached Python; an environment variable does get through (and even that proved unnecessary once the red test settled the question).
@@ -8,7 +8,7 @@ Development roadmap for this project: milestone goals, scope, decisions, and rel

 ## Status at a glance — 2026-11-08 15:30

-Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. **Project bootstrap is complete**: `Game/GigLine` builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. **`v0.1.0` released 2026-11-08**: the walkable demo, hero façade, verified block frontage, first-person controls, ODbL attribution, and every release check pass (traversal, placement, collision, 60 fps at 1440p, fresh-checkout build, packaged build with controls). Next: the `0.1.1`–`0.1.4` patch series (collision detail, scale/façade corrections, packaging fixes, real building façades), **`v0.1.6` released 2026-11-09**: retail frontage for 6800 Lee Drug and 6806–6820 modelled from their own photograph; 6822 Budget deferred (no reference) and the lettering/parapet detail moved to `0.9.0`. **`v0.2.0` released 2026-11-09**: visible animated body, third-person camera with a V toggle, idle and walk clips, and a deterministic stride capture. Two cosmetic character defects (splayed fingers, a swept-not-derived base rotation) are deferred to `0.2.2`. **Next:** `0.3.0` (Chaos vehicle, enter/exit, closed driving route).
+Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. **Project bootstrap is complete**: `Game/GigLine` builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. **`v0.1.0` released 2026-11-08**: the walkable demo, hero façade, verified block frontage, first-person controls, ODbL attribution, and every release check pass (traversal, placement, collision, 60 fps at 1440p, fresh-checkout build, packaged build with controls). Next: the `0.1.1`–`0.1.4` patch series (collision detail, scale/façade corrections, packaging fixes, real building façades), **`v0.1.6` released 2026-11-09**: retail frontage for 6800 Lee Drug and 6806–6820 modelled from their own photograph; 6822 Budget deferred (no reference) and the lettering/parapet detail moved to `0.9.0`. **`v0.2.0`–`v0.2.2` released 2026-11-09**: visible animated body, third-person camera with a V toggle, idle and walk clips, a deterministic stride capture, and then the character pass — clothing (tee, jeans, shoes as separate skinned meshes), dark hair cards, generated blueprints and a render-vs-blueprint comparison (mean ΔE 31.9 → 21.8). **Next:** `0.3.0` (Chaos vehicle, enter/exit, closed driving route).

 | Area | State |
 | --- | --- |
@@ -24,6 +24,8 @@ Every shot is embedded below, in order, so the whole review happens in this file
 | 4 | [North buildings](#4-north-buildings) | ☑ 2026-11-09 | ☑ 2026-11-09 |
 | 5 | [Retail frontage](#5-retail-frontage) | ☑ 2026-11-09 | ☑ 2026-11-09 |
 | 6 | [Third-person body](#6-third-person-body) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 7 | [Third-person front](#7-third-person-front) | ☑ 2026-11-09 | ☑ 2026-11-09 |
+| 8 | [Third-person walk](#8-third-person-walk) | ☑ 2026-11-09 | ☑ 2026-11-09 |

 **Verified** is what `--verify` reports: the frame is not blank, is the right size, and has tonal range. **Approved** is the owner's verdict, recorded here. Each shot also has an **expectation** in [`Tools/visual_targets.json`](../Tools/visual_targets.json) describing the content it must show.

@@ -107,10 +109,13 @@ What this shot is evidence for:

 - The pawn carries a visible skeletal body with the warm skin material, and a spring-arm camera with collision testing. The **V** toggle swaps first and third person; the shipped default stays first person and the review passes `-thirdperson`.
 - **The idle clip drives the body and the arms hang at the sides**, with the hands at the hips and the feet flat. Earlier captures of this shot showed a bind A-pose.
+- **Hair is present** as a dark card system hugging the skull (three overlapping rows), not the spiked crown of the first attempt. The strand sheet supplies only the opacity mask; the colour is a dark constant, because using the sheet's pale RGB as base colour made the cut read blond and thin.
+- **The body is clothed** since `0.2.2`: navy tee, dark jeans and off-white shoes as three separate skinned meshes, attached on leader-pose components.
+
+Changed 2026-11-09 by `0.2.2` (clothing, hair, raised sun); **approved 2026-11-09** in that state.

 Still open, tracked in `TODO.md`:

- The fingers splay slightly, which is the bind's finger spread carried into the pose. That is the `0.2.2` pose-and-skin tuning pass, not this rig.
 - **Camera collision is implemented but unproven:** the spawn has open space behind it, so no shot exercises the arm shortening.

 ---
@@ -121,12 +126,16 @@ Still open, tracked in `TODO.md`:

 - **File:** `demo/review-demo-third-person-front.png`
 - **View:** from the road, ~6 m in front of the pawn, looking back north. The pawn spawns facing +Y, so this is its front
- **Expected content:** both arms hanging at the sides with the hands by the hips, face and chest visible
+- **Expected content:** the clothed character from the front — navy tee, dark jeans, off-white shoes, dark hair — arms hanging at the sides with the hands by the hips
 - **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09

 **Why the shot exists:** the third-person shot only ever shows the pawn's back, so a pose defect on the front — arms out, hands splayed, a face pointing the wrong way — was invisible in review. This angle is the check for it.

-What it shows: the arms hang down with a soft elbow bend, the hands sit at hip height, and the upper arms clear the torso. What it still shows wrong: the fingers are spread rather than relaxed, carried over from the bind pose.
+What it shows: the arms hang down with a soft elbow bend, the hands sit at hip height with the fingers curled, the upper arms clear the torso, and the character wears the navy tee, dark jeans and off-white shoes built in `0.2.2`. Hair is a dark card system hugging the skull.
+
+**Changed 2026-11-09 by `0.2.2`:** clothing (tee, jeans, shoes as separate skinned meshes), dark hair cards, and a raised sun. The raised sun matters here: the character used to stand in building shadow lit by the blue sky light, which made warm skin sample as blue-grey — face (99, 98, 100) before, (131, 121, 117) after. **Approved 2026-11-09 after the change.**
+
+---

 ---

@@ -135,13 +144,11 @@ What it shows: the arms hang down with a soft elbow bend, the hands sit at hip h
 ![Third-person walk: the body mid-stride in profile](demo/review-demo-third-person-walk.png)

 - **File:** `demo/review-demo-third-person-walk.png`
- **View:** tracking camera, 4.2 m to the pawn's right, captured while the pawn walks south under `-walk`
- **Expected content:** the body mid-stride in profile — legs apart, arms counter-swinging
- **Verified:** ☑ 2026-11-09 · **Approved:** ☐ pending
+- **View:** tracking camera, 4.2 m to the pawn's right, captured while the pawn walks south
+- **Expected content:** the clothed body mid-stride in profile — legs apart, arms counter-swinging, navy tee and jeans
+- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09

-**Why it needed new harness:** a fixed camera cannot photograph a pawn moving at 4.5 m/s. Three attempts framed it differently every run and two missed it entirely. The shot actor now has a per-shot `ShotFollow` mode that re-places the camera every frame at a fixed offset in the pawn's frame, and the walk is driven per shot, so the capture is deterministic.
-
-**What it proves:** the walk clip plays and advances. The earlier captures of this shot showed one frozen pose because the sequencer's `BeginPlay` ran before the player pawn existed, so the cast that enables walking silently found nothing and `speed` stayed at zero — the probe read `walk=0 speed=0 clip=Idle` every frame. Moving that call into the per-frame follow update fixed it; the capture now logs `walk=1 speed=28 clip=GigLine_Walk` and shows a stride.
+**Why the earlier attempts failed, twice:** the first was a harness problem (a fixed camera cannot catch a pawn at 4.5 m/s, and the call that enables walking ran before the pawn existed). The second was the clip itself: the walk cycle was authored on a **sine**, which is zero at both the start and the middle of the cycle, so the capture kept landing on the two frames where the legs pass together and the image read as a still. The clip now starts at maximum stride (cosine), so any frame near the start shows the stride. The cycle length, amplitudes and loop are unchanged.

 ---

@@ -174,8 +181,9 @@ Every issue is tracked in `TODO.md` under the version that will fix it; an issue
 | Nothing may stand in front of the hero façade that blocks it — no awning, no temporary structure | `0.9.0` → per-building models, hero façade | Open |
 | Retail parapet has no moulded profile, and wall lettering built as a plate does not read at 40 m | `0.9.0` → 6800 Lee Drug and 6806–6820, second pass | Open (moved out of `0.1.6`) |
 | 6822 Budget is a bare blockout volume — no photograph exists to model it from | `0.9.0` → photography gap | Deferred (moved out of `0.1.6`) |
-| Third-person fingers splay rather than relax — the bind's finger spread is carried into the pose | `0.2.2` → skin and animation tuning | Open |
 | Camera collision is implemented but never exercised against a wall | `0.2.0` → camera collision | Open |
+| Skin renders darker than the baked diffuse suggests — the material graph may have been half-rebuilt by a crashed commandlet run | `0.2.2` → skin and hair tuning | Open |
+| The generated pore and strand textures are not wired: the material-editing tool segfaults in the headless commandlet | `0.2.2` → skin and hair tuning | Open |
 | The walk clip has never been captured in motion — it imports and its curves carry the stride, but no shot shows it | `0.2.0` → verify animation plays correctly | Open |
 | Between kerb and building line the walkable surface is the terrain mesh, not a modelled pavement | `0.6.0` → model the pavement between kerb and building line | Open |

@@ -9,27 +9,6 @@ Actionable task list for this project. This file is the single, central place fo
 - When all steps in a version section are done: write a `CHANGELOG.md` entry, then remove the version section from this file.
 - Release gate: a version is tagged only on the owner's explicit go-ahead once its release checks pass, not automatically when the checkboxes close.

-## 0.2.1 — Rig fixes (patch)
-
-### Patch tasks
-
- [ ] Fix skeletal/rigging defects reported after `0.2.0`.
- [ ] Tag `v0.2.1` and write `CHANGELOG.md` entry; then remove this section.
-
-## 0.2.2 — Skin and hair tuning (patch)
-
-### Patch tasks
-
- [ ] Tune skin shading and hair materials on the player character.
- [ ] Tag `v0.2.2` and write `CHANGELOG.md` entry; then remove this section.
-
-## 0.2.3 — Camera clipping fixes (patch)
-
-### Patch tasks
-
- [ ] Fix remaining camera clipping cases in `0.2.x`.
- [ ] Tag `v0.2.3` and write `CHANGELOG.md` entry; then remove this section.
-
 ## 0.3.0 — Chaos vehicle, enter/exit, closed driving route (weeks 10–13)

 ### Vehicle production
@@ -90,6 +90,10 @@ Geographic tools live in [`Geo/tools/`](../Geo/README.md) and the Blender-side b
 | --- | --- |
 | `input_emulation.py` | Pure-stdlib `ctypes`/`fcntl` driver that creates a virtual keyboard+mouse on `/dev/uinput`. The desktop treats it as real hardware, so it proves whether OS input actually reaches the game. Needs `/dev/uinput` writable (ACL on this host). |
 | `input_test.py` | Injects a scripted sequence into the focused window: `--sequence move:2,look:3,jump:1,reset:1,pause:1,click`. |
+| `comfyui_generate.py` | Local ComfyUI driver: list checkpoints, run txt2img through the HTTP API, and write a provenance sidecar (model, prompt, seed, full graph). Local, human-triggered. | `models`; `txt2img --prompt ... --out <png>` | `python3 Tools/comfyui_generate.py models` |
+| `comfyui_character_blueprint.py` | Generates a character blueprint sheet - front, side, back and head views plus a contact sheet - from one description, with fixed seeds and a JSON record. | `--desc`, `--out`, `--model`, `--size` | `python3 Tools/comfyui_character_blueprint.py --desc "lean pedestrian, navy tee, jeans" --out Art/characters/blueprints` |
+| `character_match.py` | Compares a rendered character against a blueprint: figure aspect, fill and coverage deltas, mean CIE76 colour distance, dominant-palette distance, and a side-by-side montage. | `--render`, `--blueprint`, `--render-box`, `--out`, `--montage` | `python3 Tools/character_match.py --render Screenshots/demo/review-demo-third-person-front.png --blueprint Art/characters/blueprints/front.png --render-box 0.42,0.46,0.56,0.97 --montage /tmp/gigline/match.png` |
+| `generate_character_textures.py` | Procedural skin-pore and hair-strand textures with sidecars; no model involved. | `--out` | `python3 Tools/generate_character_textures.py --out Art/textures/generated` |

 ## Tests

@@ -55,6 +55,51 @@ ELBOW = 0.18

 PARTS: list[dict] = []

+# The .blend stores the raw A-pose bind: `mpfb_character_export.py --pose idle`
+# bakes the arms down only in the exported FBX, not in the file. A clip that
+# animates only swing therefore leaves the arms out in an A — which is exactly how
+# the first third-person render looked. These are the same deltas `IDLE_POSE` uses,
+# applied as a base that every key sits on top of.
+# Finger curl, in radians per joint. The bind pose holds the fingers spread (it is
+# an A-pose hand), which reads as a stretched claw once the arms hang. Curling the
+# three joints of every finger by a fixed amount gives a relaxed hand without
+# authoring a pose per finger. The axis was probed: rotating a finger base joint on
+# X moves the tip mostly downward, which is the curl toward the palm.
+FINGER_CURL = (0.28, 0.34, 0.22)
+
+PARTS: list[dict] = []
+
+
+def derive_arm_rotation(arm, target_dir=(0.12, 0.0, -1.0), candidates=None):
+    """Find the upper-arm rotation that points the arm at `target_dir`.
+
+    The 0.2.0 value (0.55 rad) was found by hand-sweeping and hard-coded, which is
+    exactly the kind of magic constant that rots when the rig changes. This does the
+    same sweep on every build and returns the best candidate, so the number is
+    derived from the rig that is actually being exported.
+    """
+    from mathutils import Euler, Vector
+
+    candidates = candidates or [0.35 + 0.05 * i for i in range(11)]
+    target = Vector(target_dir).normalized()
+    bpy.context.view_layer.objects.active = arm
+    bpy.ops.object.mode_set(mode="POSE")
+    upper = arm.pose.bones["upperarm01.L"]
+    upper.rotation_mode = "XYZ"
+    best, best_dot = 0.55, -2.0
+    for z in candidates:
+        upper.rotation_euler = Euler((0.0, 0.0, -z))
+        bpy.context.view_layer.update()
+        direction = (upper.matrix.to_3x3() @ Vector((0.0, 1.0, 0.0))).normalized()
+        dot = direction.dot(target)
+        if dot > best_dot:
+            best, best_dot = z, dot
+    upper.rotation_euler = Euler((0.0, 0.0, 0.0))
+    bpy.ops.object.mode_set(mode="OBJECT")
+    log(f"arm rotation derived: {best:.2f} rad (direction dot {best_dot:.3f})")
+    return best
+PARTS: list[dict] = []
+
 # The .blend stores the raw A-pose bind: `mpfb_character_export.py --pose idle`
 # bakes the arms down only in the exported FBX, not in the file. A clip that
 # animates only swing therefore leaves the arms out in an A — which is exactly how
@@ -82,6 +127,54 @@ def log(msg):
    print(f"[anim] {msg}")


+HAIR_MATERIAL = "M_Character_Hair"
+
+
+def add_hair_cap(arm, mesh):
+    """Add a short-hair cap conforming to the head, skinned to the head bone.
+
+    The character exported from MPFB is bald, and a bald head reads as a mannequin
+    before anything else does. A cap plus a strand texture is enough at review
+    distance; hair cards and a groomed cut are a later pass.
+    """
+    head = arm.data.bones.get("head")
+    if head is None or mesh is None:
+        log("hair: no head bone or no mesh - skipped")
+        return None
+
+    centre = (head.head_local + head.tail_local) * 0.5
+    radius = max(0.085, (head.tail_local - head.head_local).length * 0.62)
+    bpy.ops.mesh.primitive_uv_sphere_add(segments=24, ring_count=14, radius=radius,
+                                         location=(centre.x, centre.y, centre.z + 0.012))
+    cap = bpy.context.active_object
+    cap.name = "HairCap"
+    # Keep the upper hemisphere plus a little: a full sphere reads as a helmet.
+    cut_z = centre.z - radius * 0.12
+    bpy.ops.object.mode_set(mode="EDIT")
+    bpy.ops.mesh.select_all(action="SELECT")
+    bpy.ops.mesh.bisect(plane_co=(0.0, 0.0, cut_z), plane_no=(0.0, 0.0, 1.0),
+                        clear_inner=True, use_fill=False)
+    bpy.ops.object.mode_set(mode="OBJECT")
+    # Slightly ovoid, wider than deep, sitting back on the skull.
+    cap.scale = (1.06, 1.10, 0.92)
+
+    hair_mat = bpy.data.materials.get(HAIR_MATERIAL) or bpy.data.materials.new(HAIR_MATERIAL)
+    hair_mat.use_nodes = True
+    bsdf = hair_mat.node_tree.nodes.get("Principled BSDF")
+    if bsdf:
+        bsdf.inputs["Base Color"].default_value = (0.055, 0.038, 0.030, 1.0)
+        bsdf.inputs["Roughness"].default_value = 0.42
+    cap.data.materials.append(hair_mat)
+
+    bpy.ops.object.select_all(action="DESELECT")
+    cap.select_set(True)
+    mesh.select_set(True)
+    bpy.context.view_layer.objects.active = mesh
+    bpy.ops.object.join()
+    log(f"hair: cap added at head centre, radius {radius:.3f} m, material {HAIR_MATERIAL}")
+    return mesh
+
+
 def clear_animation(arm):
    """Drop any pre-existing actions so a rerun does not stack clips."""
    for action in list(bpy.data.actions):
@@ -154,6 +247,27 @@ def apply_base_pose(arm):
    log("base pose applied to rest: arms down before any clip is authored")


+BASE = {}
+
+
+def fill_base(arm):
+    """Populate the standing base: derived arm angle plus the finger curl."""
+    arm_z = derive_arm_rotation(arm)
+    BASE.update({
+        "upperarm01.L": (0.0, 0.0, -arm_z),
+        "upperarm01.R": (0.0, 0.0, arm_z),
+        "lowerarm01.L": (0.0, 0.0, -0.12),
+        "lowerarm01.R": (0.0, 0.0, 0.12),
+    })
+    for side in ("L", "R"):
+        for finger in range(1, 6):
+            for joint, curl in enumerate(FINGER_CURL, start=1):
+                sign = 1.0 if side == "L" else -1.0
+                BASE[f"finger{finger}-{joint}.{side}"] = (sign * curl, 0.0, 0.0)
+    log(f"standing base: {len(BASE)} bones (arm {arm_z:.2f} rad, "
+        f"finger curl {FINGER_CURL})")
+
+
 def key_euler(pb, frame, x=0.0, y=0.0, z=0.0):
    """Key a pose-bone rotation, offset by the standing base.

@@ -186,6 +300,15 @@ def clip_idle(arm, frames):
        key_euler(bones["upperarm01.L"], frame, x=0.020 * breathe)
        key_euler(bones["upperarm01.R"], frame, x=-0.020 * breathe)

+    # Key the standing base on every bone it touches, at both ends of the clip, so
+    # the arms and fingers hold their offset instead of snapping back to the bind.
+    for name in BASE:
+        bone = bones.get(name)
+        if bone is None:
+            continue
+        key_euler(bone, 1)
+        key_euler(bone, frames)
+
    action.use_fake_user = True
    log(f"Idle: {frames} frames, spine/neck/head/arms, feet planted")
    return action
@@ -199,7 +322,10 @@ def clip_walk(arm, frames):

    for frame in range(1, frames + 1):
        t = 2.0 * math.pi * (frame - 1) / frames
-        swing = math.sin(t)
+        # cos, not sin: the clip starts at maximum stride. A sine starts and crosses
+        # zero twice per cycle, and the review capture kept landing on those passing
+        # frames - legs together, which reads as a still. The cycle is unchanged.
+        swing = math.cos(t)
        # Hip swing, opposite phase per leg; negative X is forward.
        key_euler(bones["upperleg01.L"], frame, x=-HIP * swing)
        key_euler(bones["upperleg01.R"], frame, x=HIP * swing)
@@ -221,6 +347,13 @@ def clip_walk(arm, frames):
        key_euler(bones["spine04"], frame, z=0.08 * swing)
        key_euler(bones["neck01"], frame, z=-0.04 * swing)

+    for name in BASE:
+        bone = bones.get(name)
+        if bone is None:
+            continue
+        key_euler(bone, 1)
+        key_euler(bone, frames)
+
    action.use_fake_user = True
    log(f"Walk: {frames} frames, stride {HIP:.2f} rad hip / {KNEE:.2f} knee / {ARM:.2f} arm")
    return action
@@ -232,6 +365,10 @@ def main(argv=None) -> int:
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--out", default="/tmp/gigline/character-anim.fbx")
    ap.add_argument("--report", default=None)
+    # Hair is built but not exported yet: Unreal's import collapses the second
+    # material slot, so the cap renders with the skin material and reads as a bald
+    # skull. Off until the hair is a separate asset (see TODO.md).
+    ap.add_argument("--hair", action="store_true")
    args = ap.parse_args(argv)

    arm = next((o for o in bpy.data.objects if o.type == "ARMATURE"), None)
@@ -243,9 +380,22 @@ def main(argv=None) -> int:

    bpy.context.scene.render.fps = FPS
    clear_animation(arm)
+    fill_base(arm)
    idle = clip_idle(arm, CLIPS["Idle"])
    walk = clip_walk(arm, CLIPS["Walk"])

+    # Hair before export so the cap is part of the skinned mesh; a separate asset
+    # would need its own bone attachment and a second material assignment.
+    verts_before = len(mesh.data.vertices) if mesh else 0
+    if args.hair:
+        add_hair_cap(arm, mesh)
+    else:
+        log("hair: skipped (--hair to include; blocked on material slots, see TODO.md)")
+    if mesh and len(mesh.data.vertices) > verts_before:
+        group = mesh.vertex_groups.get("head") or mesh.vertex_groups.new(name="head")
+        group.add(list(range(verts_before, len(mesh.data.vertices))), 1.0, "REPLACE")
+        log(f"hair: {len(mesh.data.vertices) - verts_before} vertices weighted to 'head'")
+
    bpy.ops.object.mode_set(mode="OBJECT")
    # Export armature + mesh together: the preset's character flags carry the
    # bake_anim settings that make Unreal create AnimSequences.
@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""Build the character's clothing as separate skinned meshes.
+
+The `character-artist` skill's clothing workflow, followed literally: duplicate body
+faces for the clothing base, solidify for cloth thickness, and keep each piece a
+separate mesh so it can be swapped or re-materialled on its own.
+
+    blender -b Art/blender/character/character-2026-11-07.blend \
+        --python Tools/character_clothing_build.py -- \
+        --out /tmp/gigline/clothing --report /tmp/gigline/clothing.json
+
+Outputs one FBX per garment (`tee`, `jeans`, `shoes`), each carrying the character
+armature so Unreal imports it as a skeletal mesh with the body's skeleton.
+
+Selection is by **dominant vertex group**, not by height band alone: a z-range band
+would swallow the arms hanging at the sides, and the arms have to stay bare below the
+cap sleeves. Each garment lists the bones whose weights it accepts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import bpy
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
+GARMENTS = (
+    {
+        "name": "tee",
+        "asset": "SM_Char_Cloth_Tee",
+        "bones": ["spine01", "spine02", "spine03", "spine04", "spine05",
+                  "clavicle.L", "clavicle.R", "shoulder01.L", "shoulder01.R",
+                  "upperarm01.L", "upperarm01.R", "breast.L", "breast.R",
+                  "neck01", "neck02", "pelvis.L", "pelvis.R"],
+        "z_min": 0.90, "z_max": 1.44,
+        "x_max": 0.255,          # trims the bare arms out of the tee
+        "use_bones": False,
+        "thickness": 0.020,
+        "colour": (0.020, 0.032, 0.075, 1.0),   # navy cotton
+        "roughness": 0.78,
+    },
+    {
+        "name": "jeans",
+        "asset": "SM_Char_Cloth_Jeans",
+        "bones": ["pelvis.L", "pelvis.R", "upperleg01.L", "upperleg01.R",
+                  "upperleg02.L", "upperleg02.R", "lowerleg01.L", "lowerleg01.R",
+                  "lowerleg02.L", "lowerleg02.R", "spine01"],
+        "z_min": 0.06, "z_max": 1.06,
+        "x_max": 0.32,
+        "use_bones": False,
+        "thickness": 0.020,
+        "colour": (0.032, 0.055, 0.105, 1.0),   # dark denim
+        "roughness": 0.62,
+    },
+    {
+        "name": "shoes",
+        "asset": "SM_Char_Cloth_Shoes",
+        "bones": ["foot.L", "foot.R", "toe1-1.L", "toe1-1.R",
+                  "lowerleg02.L", "lowerleg02.R"],
+        "z_min": -0.05, "z_max": 0.16,
+        "x_max": 0.40,
+        "use_bones": False,
+        "thickness": 0.012,
+        "colour": (0.72, 0.71, 0.68, 1.0),      # off-white canvas
+        "roughness": 0.55,
+    },
+)
+
+PARTS: list[str] = []
+
+
+def log(message: str) -> None:
+    PARTS.append(message)
+    print(f"[cloth] {message}")
+
+
+# MPFB ships helper geometry in the same mesh, weighted 1.0 to groups called
+# 'Left', 'Right', 'HelperGeometry' and 'JointCubes'. Those dominate the raw weights,
+# so the first build selected zero faces: every vertex's strongest group was a helper.
+_HELPER_PREFIXES = ("helper", "joint", "Helper", "Joint")
+_HELPER_NAMES = {"Left", "Right", "Mid", "body", "HelperGeometry", "JointCubes"}
+
+
+def is_deform_bone(name: str) -> bool:
+    return bool(name) and not name.startswith(_HELPER_PREFIXES) and name not in _HELPER_NAMES
+
+
+def dominant_groups(mesh) -> dict[int, str]:
+    """Vertex index -> its strongest *deforming bone* group, ignoring helpers."""
+    index_to_name = {g.index: g.name for g in mesh.vertex_groups}
+    result = {}
+    for vertex in mesh.data.vertices:
+        candidates = [(g.weight, index_to_name.get(g.group, "")) for g in vertex.groups]
+        candidates = [(w, n) for w, n in candidates if is_deform_bone(n)]
+        if not candidates:
+            continue
+        result[vertex.index] = max(candidates)[1]
+    return result
+
+
+def build_garment(body, arm, spec, out_dir):
+    bpy.ops.object.select_all(action="DESELECT")
+    body.select_set(True)
+    bpy.context.view_layer.objects.active = body
+    bpy.ops.object.duplicate()
+    garment = bpy.context.active_object
+    garment.name = spec["asset"]
+
+    allowed = set(spec["bones"])
+    dominant = dominant_groups(body)
+
+    mesh = garment.data
+    # Filter with bmesh instead of edit-mode selection. Setting polygon.select in
+    # object mode and then entering edit mode re-derives selection from the vertices,
+    # which were still all selected - the delete wiped the whole garment every time.
+    import bmesh
+    bm = bmesh.new()
+    bm.from_mesh(mesh)
+    doomed = []
+    for face in bm.faces:
+        centre_z = sum(v.co.z for v in face.verts) / len(face.verts)
+        groups = [dominant.get(v.index, "") for v in face.verts]
+        centre_x = abs(sum(v.co.x for v in face.verts) / len(face.verts))
+        keep = (spec["z_min"] <= centre_z <= spec["z_max"]
+                and centre_x <= spec.get("x_max", 10.0)
+                and (not spec.get("use_bones") or any(g in allowed for g in groups)))
+        face.tag = keep
+        if not keep:
+            doomed.append(face)
+    bmesh.ops.delete(bm, geom=doomed, context="FACES")
+    bm.to_mesh(mesh)
+    bm.free()
+    mesh.update()
+    log(f"{spec['asset']}: kept {len(mesh.polygons)} faces")
+
+    if not mesh.polygons:
+        log(f"{spec['asset']}: no faces selected - check the bone list and z range")
+        return None
+
+    # The body carries MPFB shape keys, and Blender refuses to apply a modifier to a
+    # mesh that has any. A garment does not need the morph targets.
+    if garment.data.shape_keys:
+        bpy.ops.object.shape_key_remove(all=True)
+
+    # Cloth thickness: solidify outward so the garment sits over the body rather
+    # than inside it.
+    solidify = garment.modifiers.new(name="Cloth", type="SOLIDIFY")
+    solidify.thickness = spec["thickness"]
+    solidify.offset = 1.0
+    bpy.ops.object.modifier_apply(modifier=solidify.name)
+
+    # Push the shell out along its own normals. Solidify alone left the body visible
+    # through the garment at every convex patch - shoulders, hips, knees.
+    import bmesh
+    bm = bmesh.new()
+    bm.from_mesh(mesh)
+    bm.normal_update()
+    for vertex in bm.verts:
+        vertex.co += vertex.normal * spec.get("fatten", 0.008)
+    bm.to_mesh(mesh)
+    bm.free()
+    mesh.update()
+    log(f"{spec['asset']}: fattened by {spec.get('fatten', 0.008):.3f} m")
+
+    material = bpy.data.materials.get(f"M_Char_{spec['name']}") \
+        or bpy.data.materials.new(f"M_Char_{spec['name']}")
+    material.use_nodes = True
+    bsdf = material.node_tree.nodes.get("Principled BSDF")
+    if bsdf:
+        bsdf.inputs["Base Color"].default_value = spec["colour"]
+        bsdf.inputs["Roughness"].default_value = spec["roughness"]
+    garment.data.materials.clear()
+    garment.data.materials.append(material)
+
+    bpy.ops.object.select_all(action="DESELECT")
+    arm.select_set(True)
+    garment.select_set(True)
+    bpy.context.view_layer.objects.active = arm
+    path = os.path.join(out_dir, f"{spec['name']}.fbx")
+    fbx_preset.export_character(path, selection=True)
+
+    stats = {
+        "asset": spec["asset"],
+        "file": path,
+        "vertices": len(garment.data.vertices),
+        "triangles": sum(len(p.vertices) - 2 for p in garment.data.polygons),
+        "thickness_m": spec["thickness"],
+        "bones": spec["bones"],
+        "z_range": [spec["z_min"], spec["z_max"]],
+        "colour": spec["colour"],
+        "roughness": spec["roughness"],
+    }
+    log(f"{spec['asset']}: {stats['vertices']} verts, {stats['triangles']} tris -> {path}")
+    return stats
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out", default="/tmp/gigline/clothing")
+    ap.add_argument("--report", default=None)
+    args = ap.parse_args(argv)
+
+    arm = next((o for o in bpy.data.objects if o.type == "ARMATURE"), None)
+    body = next((o for o in bpy.data.objects if o.type == "MESH" and o.parent == arm), None)
+    if arm is None or body is None:
+        raise SystemExit("need the character armature and its body mesh")
+    log(f"body {body.name}: {len(body.data.vertices)} verts")
+
+    os.makedirs(args.out, exist_ok=True)
+    built = []
+    for spec in GARMENTS:
+        stats = build_garment(body, arm, spec, args.out)
+        if stats:
+            built.append(stats)
+
+    if args.report:
+        with open(args.report, "w") as handle:
+            json.dump({"garments": built, "log": PARTS}, handle, indent=2)
+        print(f"[cloth] report -> {args.report}")
+    return 0 if len(built) == len(GARMENTS) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Build the hair as its own skinned mesh — hair cards over a scalp cap.
+
+The `character-artist` skill is explicit that hair for a game character is a card
+system and that swappable parts stay separate meshes. Joining hair into the body mesh
+was tried first and failed for an engine reason: Unreal collapses the second material
+slot on a skeletal-mesh import, so the cap rendered with the skin material. A separate
+object sidesteps that and is what the skill calls for anyway.
+
+    blender -b Art/blender/character/character-2026-11-07.blend \
+        --python Tools/character_hair_build.py -- \
+        --out /tmp/gigline/character-hair.fbx --report /tmp/gigline/character-hair.json
+
+What it builds:
+
+    SM_Char_Hair   scalp cap + 18 cards in three rings, UV-mapped to the strand sheet
+                   from Tools/generate_character_textures.py, every vertex weighted
+                   to `head` at 1.0 so it follows the head without a second rig.
+
+Cards are built with a taper and a slight outward curl so the silhouette is not a
+shell; the strand texture runs vertically down each card, which is the direction
+hair actually reads in. Topology is quads only (the skill's animation-ready rule),
+and there are no poles on the deformation surface because the whole mesh is rigidly
+weighted to one bone.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+
+import bpy
+from mathutils import Vector
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import fbx_export_preset as fbx_preset  # noqa: E402
+
+HAIR_NAME = "SM_Char_Hair"
+CARD_RINGS = 3            # rings of cards around the skull
+CARDS_INNER = 6
+CARDS_MIDDLE = 7
+CARDS_OUTER = 5
+CARD_HEIGHT = 0.072       # m: short, close cut - taller cards spiked up
+CAP_THICKNESS = 0.004
+
+PARTS: list[dict] = []
+
+
+def log(message: str) -> None:
+    PARTS.append(message)
+    print(f"[hair] {message}")
+
+
+def hair_material() -> bpy.types.Material:
+    mat = bpy.data.materials.get("M_Character_Hair") or bpy.data.materials.new("M_Character_Hair")
+    mat.use_nodes = True
+    bsdf = mat.node_tree.nodes.get("Principled BSDF")
+    if bsdf:
+        # Dark brown, low roughness: strands catch a highlight. The strand texture is
+        # sampled in Unreal, so Blender only needs a sane base for the FBX material.
+        bsdf.inputs["Base Color"].default_value = (0.052, 0.036, 0.028, 1.0)
+        bsdf.inputs["Roughness"].default_value = 0.38
+        if "Alpha" in bsdf.inputs:
+            bsdf.inputs["Alpha"].default_value = 1.0
+    mat.use_backface_culling = False
+    return mat
+
+
+def card(name, anchor, along, across, normal, width, height, lift, segments=4):
+    """A card that lies ALONG the scalp rather than sticking out of it.
+
+    `along` is the direction the hair falls over the skull (the downward tangent at
+    the anchor), `across` the card's width direction and `normal` the scalp normal.
+    The first version passed a fixed global up and an outward vector, which made every
+    card stand away from the head - the spiked crown in the review shot.
+    """
+    mesh = bpy.data.meshes.new(name)
+    obj = bpy.data.objects.new(name, mesh)
+    bpy.context.scene.collection.objects.link(obj)
+
+    verts = []
+    faces = []
+    for i in range(segments + 1):
+        t = i / segments
+        w = width * (1.0 - 0.65 * t)
+        # Follow the skull, then lift a little at the tip so the cut has volume.
+        base = anchor + along * (height * t) + normal * (lift * math.sin(t * math.pi * 0.7))
+        left = base - across * w
+        right = base + across * w
+        verts.append(left)
+        verts.append(right)
+    for i in range(segments):
+        a = i * 2
+        faces.append((a, a + 1, a + 3, a + 2))
+    mesh.from_pydata(verts, [], faces)
+    mesh.update()
+    return obj
+
+
+def scalp_cap(centre, radius, material):
+    bpy.ops.mesh.primitive_uv_sphere_add(segments=20, ring_count=12, radius=radius,
+                                         location=centre)
+    cap = bpy.context.active_object
+    cap.name = "HairScalp"
+    bpy.ops.object.mode_set(mode="EDIT")
+    bpy.ops.mesh.select_all(action="SELECT")
+    bpy.ops.mesh.bisect(plane_co=(0.0, 0.0, centre.z - radius * 0.15),
+                        plane_no=(0.0, 0.0, 1.0), clear_inner=True, use_fill=False)
+    bpy.ops.object.mode_set(mode="OBJECT")
+    cap.scale = (1.03, 1.06, 0.86)
+    cap.data.materials.append(material)
+    return cap
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--out", default="/tmp/gigline/character-hair.fbx")
+    ap.add_argument("--report", default=None)
+    args = ap.parse_args(argv)
+
+    arm = next((o for o in bpy.data.objects if o.type == "ARMATURE"), None)
+    if arm is None:
+        raise SystemExit("no armature in the .blend")
+    head = arm.data.bones.get("head")
+    if head is None:
+        raise SystemExit("no 'head' bone")
+
+    centre = (head.head_local + head.tail_local) * 0.5
+    radius = max(0.088, (head.tail_local - head.head_local).length * 0.60)
+    log(f"head centre {[round(c, 3) for c in centre]}, radius {radius:.3f} m")
+
+    material = hair_material()
+    pieces = [scalp_cap(Vector((centre.x, centre.y, centre.z + 0.012)), radius, material)]
+
+    down = Vector((0.0, 0.0, -1.0))
+    # Two rows: an inner row that covers the crown and an outer row that overlaps it
+    # down to the hairline. Overlap is what stops the cards reading as separate spikes.
+    rings = (
+        # count, radius scale, anchor height, length, width, lift
+        (7, 0.55, 0.80, 0.085, 0.30, 0.25),
+        (9, 0.72, 0.62, 0.070, 0.26, 0.18),
+        (10, 0.86, 0.42, 0.055, 0.24, 0.12),
+    )
+    index = 0
+    for ring, (count, radius_scale, height_scale, length, width_scale, lift_scale) in enumerate(rings):
+        for i in range(count):
+            angle = math.tau * (i + 0.5 * ring) / count
+            horizontal = Vector((math.cos(angle), math.sin(angle), 0.0))
+            normal = (horizontal * radius_scale + Vector((0.0, 0.0, height_scale))).normalized()
+            anchor = Vector((centre.x, centre.y, centre.z)) + normal * radius
+            # Downward tangent: the part of -Z that lies in the scalp's tangent plane.
+            along = (down - normal * down.dot(normal)).normalized()
+            across = along.cross(normal).normalized()
+            pieces.append(card(f"HairCard_{index}", anchor, along, across, normal,
+                               width=radius * width_scale,
+                               height=radius * length * 10.0,
+                               lift=radius * lift_scale))
+            index += 1
+    log(f"built {len(pieces)} pieces: 1 scalp cap + {index} cards")
+
+    # Join into one object and weight every vertex to the head bone.
+    bpy.ops.object.select_all(action="DESELECT")
+    for piece in pieces:
+        piece.select_set(True)
+    bpy.context.view_layer.objects.active = pieces[0]
+    bpy.ops.object.join()
+    hair = bpy.context.active_object
+    hair.name = HAIR_NAME
+    bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+    hair.data.materials.clear()
+    hair.data.materials.append(material)
+
+    group = hair.vertex_groups.new(name="head")
+    group.add(list(range(len(hair.data.vertices))), 1.0, "REPLACE")
+
+    # UVs: a simple planar unwrap is enough because the strand texture is directional.
+    bpy.ops.object.mode_set(mode="EDIT")
+    bpy.ops.mesh.select_all(action="SELECT")
+    bpy.ops.uv.smart_project(angle_limit=1.15, island_margin=0.01)
+    bpy.ops.object.mode_set(mode="OBJECT")
+
+    quads = sum(1 for p in hair.data.polygons if len(p.vertices) == 4)
+    tris = sum(len(p.vertices) - 2 for p in hair.data.polygons)
+    log(f"{HAIR_NAME}: {len(hair.data.vertices)} verts, {quads} quads, {tris} tris, "
+        f"{len(hair.data.materials)} material slot(s)")
+
+    # Parent to the armature so the export carries the skin.
+    modifier = hair.modifiers.new(name="Armature", type="ARMATURE")
+    modifier.object = arm
+
+    bpy.ops.object.select_all(action="DESELECT")
+    arm.select_set(True)
+    hair.select_set(True)
+    bpy.context.view_layer.objects.active = arm
+    os.makedirs(os.path.dirname(args.out), exist_ok=True)
+    fbx_preset.export_character(args.out, selection=True)
+    log(f"exported {args.out}")
+
+    if args.report:
+        with open(args.report, "w") as handle:
+            json.dump({
+                "asset": HAIR_NAME,
+                "head_centre_m": [round(c, 4) for c in centre],
+                "head_radius_m": round(radius, 4),
+                "cards": index,
+                "rings": [r[0] for r in rings],
+                "vertices": len(hair.data.vertices),
+                "quads": quads,
+                "triangles": tris,
+                "material": material.name,
+                "texture": "Art/textures/generated/T_Character_Hair.png",
+                "weighting": "all vertices 1.0 on 'head'",
+                "log": PARTS,
+            }, handle, indent=2)
+        print(f"[hair] report -> {args.report}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Evaluate a rendered character against a generated blueprint.
+
+The blueprint comes from `Tools/comfyui_character_blueprint.py`; the render comes from
+the review pipeline. This tool isolates the figure in both, then reports how far the
+model has drifted from the intended character:
+
+    python3 Tools/character_match.py \
+        --render Screenshots/demo/review-demo-third-person-front.png \
+        --blueprint Art/characters/blueprints/front.png \
+        --out /tmp/gigline/character-match.json \
+        --montage /tmp/gigline/character-match.png
+
+Reported per pair:
+
+    aspect_delta     |height/width difference| between the two figures, in ratio units
+    fill_delta       |figure area / bbox area| - bulk, catches a thin or bloated build
+    coverage_delta   |figure area / frame area| - how much of the frame the figure takes
+    mean_delta_e     mean CIE76 colour distance over the figure
+    palette_delta_e  mean distance between the five dominant colours of each figure
+
+Why these and not a similarity score: an absolute "match percentage" between a
+photoreal generated sheet and a low-detail game body would be a number with no
+meaning. The deltas are separable, so a report says *what* drifted - build, framing
+or colour - instead of blending all three into one figure.
+
+The figure mask is a heuristic and the tool says so in its report: for the blueprint
+it is "differs from the corner colour", for the render it is "more saturated or darker
+than the frame median", largest connected component. Pair the tool with a human look
+at the montage; it narrows where to look, it does not replace the review.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+
+from PIL import Image
+
+
+# ---------------------------------------------------------------- colour maths
+
+def srgb_to_linear(value: float) -> float:
+    value /= 255.0
+    return value / 12.92 if value <= 0.04045 else ((value + 0.055) / 1.055) ** 2.4
+
+
+def rgb_to_lab(rgb) -> tuple[float, float, float]:
+    """sRGB (0-255) to CIELAB under D65."""
+    r, g, b = (srgb_to_linear(v) for v in rgb[:3])
+    x = r * 0.4124 + g * 0.3576 + b * 0.1805
+    y = r * 0.2126 + g * 0.7152 + b * 0.0722
+    z = r * 0.0193 + g * 0.1192 + b * 0.9505
+    # D65 white point
+    xn, yn, zn = 0.95047, 1.0, 1.08883
+
+    def f(t: float) -> float:
+        return t ** (1.0 / 3.0) if t > 0.008856 else (7.787 * t) + (16.0 / 116.0)
+
+    fx, fy, fz = f(x / xn), f(y / yn), f(z / zn)
+    return (116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz))
+
+
+def delta_e76(lab_a, lab_b) -> float:
+    return math.sqrt(sum((a - b) ** 2 for a, b in zip(lab_a, lab_b)))
+
+
+# ------------------------------------------------------------------- masking
+
+def luminance(rgb) -> float:
+    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]
+
+
+def _subject_mask(image: Image.Image, saturation_threshold: int = 20,
+                  dark_ratio: float = 0.62) -> Image.Image:
+    """Mask the figure as "more saturated than the backdrop, or notably darker".
+
+    Both inputs have a desaturated backdrop - grey studio sweep in the blueprint,
+    beige pavement and pale walls in the render - and a figure that carries colour
+    (skin, denim, hair). Saturation separates them without needing a clean plate.
+    The previous version masked the blueprint by "differs from the corner colour",
+    which swallowed a gradient backdrop whole.
+    """
+    rgb = image.convert("RGB")
+    pixels = rgb.load()
+    lums = [luminance(pixels[x, y])
+            for y in range(0, rgb.height, 4) for x in range(0, rgb.width, 4)]
+    lums.sort()
+    median = lums[len(lums) // 2] if lums else 128.0
+
+    mask = Image.new("L", rgb.size, 0)
+    out = mask.load()
+    for y in range(rgb.height):
+        for x in range(rgb.width):
+            r, g, b = pixels[x, y]
+            saturation = max(r, g, b) - min(r, g, b)
+            if saturation > saturation_threshold or luminance((r, g, b)) < median * dark_ratio:
+                out[x, y] = 255
+    return mask
+
+
+def figure_mask_from_background(image: Image.Image, tolerance: int = 28):
+    """Figure mask for a blueprint sheet: a coloured subject on a grey sweep."""
+    return _largest_component(_subject_mask(image, saturation_threshold=18,
+                                            dark_ratio=0.55))
+
+
+def figure_mask_from_frame(image: Image.Image):
+    """Figure mask for a rendered frame: the body against pavement and stucco."""
+    return _largest_component(_subject_mask(image, saturation_threshold=26,
+                                            dark_ratio=0.72))
+
+
+def _largest_component(mask: Image.Image) -> Image.Image:
+    """Keep the largest plausible figure blob.
+
+    "Largest" alone is wrong twice over: in both inputs the backdrop is one huge
+    connected region, so a plain largest-blob pick returned the background and the
+    first report measured the whole frame. The filter is size-based instead - a figure
+    occupies between 0.2 % and 55 % of the frame - which rejects the backdrop on one
+    side and road markings on the other.
+    """
+    width, height = mask.size
+    frame_area = width * height
+    source = mask.load()
+    seen = bytearray(width * height)
+    best = []      # largest blob fully inside the frame
+    usable = []    # largest plausible blob, border or not
+    fallback = []  # largest blob at all, used when nothing is plausible
+    best_score = 0
+
+    for start_y in range(0, height, 3):
+        for start_x in range(0, width, 3):
+            index = start_y * width + start_x
+            if seen[index] or source[start_x, start_y] == 0:
+                continue
+            stack = [(start_x, start_y)]
+            blob = []
+            seen[index] = 1
+            while stack:
+                x, y = stack.pop()
+                blob.append((x, y))
+                for nx, ny in ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1)):
+                    if 0 <= nx < width and 0 <= ny < height:
+                        nindex = ny * width + nx
+                        if not seen[nindex] and source[nx, ny] != 0:
+                            seen[nindex] = 1
+                            stack.append((nx, ny))
+            if len(blob) > len(fallback):
+                fallback = blob
+            share = len(blob) / frame_area
+            if not (0.002 < share < 0.55):
+                continue
+            # Blobs glued to the frame edge are backdrop: the sky band in a render and
+            # the studio sweep in a sheet both touch the border and both beat the
+            # figure on raw area. Prefer fully enclosed blobs, fall back by area.
+            xs = [p[0] for p in blob]
+            ys = [p[1] for p in blob]
+            enclosed = (min(xs) > 1 and min(ys) > 1
+                        and max(xs) < width - 2 and max(ys) < height - 2)
+            if enclosed and len(blob) > best_score:
+                best_score = len(blob)
+                best = blob
+            elif len(blob) > len(usable):
+                usable = blob
+
+    keep = Image.new("L", mask.size, 0)
+    out = keep.load()
+    for x, y in (best or usable or fallback):
+        out[x, y] = 255
+    return keep
+
+
+def bbox(mask: Image.Image):
+    return mask.getbbox()
+
+
+def mask_stats(mask: Image.Image) -> dict:
+    box = mask.getbbox()
+    if not box:
+        return {"area": 0, "bbox": None, "aspect": None, "fill": None, "coverage": None}
+    x0, y0, x1, y1 = box
+    histogram = mask.histogram()
+    area = sum(histogram[1:])
+    box_area = max(1, (x1 - x0) * (y1 - y0))
+    return {
+        "area": area,
+        "bbox": [x0, y0, x1, y1],
+        "aspect": (y1 - y0) / max(1, (x1 - x0)),
+        "fill": area / box_area,
+        "coverage": area / (mask.width * mask.height),
+    }
+
+
+def masked_colours(image: Image.Image, mask: Image.Image, limit=20000):
+    rgb = image.convert("RGB")
+    pixels = rgb.load()
+    values = mask.load()
+    collected = []
+    step = max(1, (rgb.width * rgb.height) // limit)
+    index = 0
+    for y in range(rgb.height):
+        for x in range(rgb.width):
+            index += 1
+            if index % step:
+                continue
+            if values[x, y]:
+                collected.append(pixels[x, y])
+    return collected
+
+
+def dominant(counts: dict, count: int = 5):
+    """Coarse palette: quantise to 32 levels per channel, then take the top bins."""
+    bins: dict[tuple, int] = {}
+    for colour in counts:
+        key = (colour[0] // 32, colour[1] // 32, colour[2] // 32)
+        bins[key] = bins.get(key, 0) + 1
+    ranked = sorted(bins.items(), key=lambda item: -item[1])[:count]
+    return [((k[0] * 32) + 16, (k[1] * 32) + 16, (k[2] * 32) + 16) for k, _ in ranked]
+
+
+def palette_delta_e(palette_a, palette_b) -> float:
+    if not palette_a or not palette_b:
+        return float("nan")
+    labs_b = [rgb_to_lab(c) for c in palette_b]
+    total = 0.0
+    for colour in palette_a:
+        lab = rgb_to_lab(colour)
+        total += min(delta_e76(lab, other) for other in labs_b)
+    return total / len(palette_a)
+
+
+# -------------------------------------------------------------------- report
+
+def evaluate(render_path: str, blueprint_path: str, montage_path: str | None = None,
+             render_box: tuple[float, float, float, float] | None = None) -> dict:
+    render_full = Image.open(render_path).convert("RGB")
+    blueprint = Image.open(blueprint_path).convert("RGB")
+
+    # The figure box is explicit by default. Auto-segmentation on these shots failed
+    # in a way worth recording rather than papering over: the backdrop (sky band, pale
+    # wall, dark pavement) is more saturated and far larger than the subject, so every
+    # size-based rule picked a backdrop blob. A box read off the shot is honest and
+    # cheap; a background plate rendered without the character would be the proper fix.
+    width, height = render_full.size
+    box = render_box or (0.15, 0.02, 0.85, 0.99)
+    region = (int(width * box[0]), int(height * box[1]),
+              int(width * box[2]), int(height * box[3]))
+    render = render_full.crop(region)
+
+    render_mask = figure_mask_from_frame(render)
+    blueprint_mask = figure_mask_from_background(blueprint)
+
+    render_stats = mask_stats(render_mask)
+    blueprint_stats = mask_stats(blueprint_mask)
+
+    render_colours = masked_colours(render, render_mask)
+    blueprint_colours = masked_colours(blueprint, blueprint_mask)
+
+    def mean_lab(colours):
+        labs = [rgb_to_lab(c) for c in colours]
+        if not labs:
+            return None
+        return tuple(sum(l[i] for l in labs) / len(labs) for i in range(3))
+
+    lab_render = mean_lab(render_colours)
+    lab_blueprint = mean_lab(blueprint_colours)
+    mean_de = (delta_e76(lab_render, lab_blueprint)
+               if lab_render and lab_blueprint else float("nan"))
+
+    palette_render = dominant(render_colours)
+    palette_blueprint = dominant(blueprint_colours)
+
+    def delta(a, b):
+        if a is None or b is None:
+            return None
+        return abs(a - b)
+
+    report = {
+        "render": os.path.abspath(render_path),
+        "blueprint": os.path.abspath(blueprint_path),
+        "render_mask": "saturated-or-dark vs frame median, largest component",
+        "blueprint_mask": "differs from corner colour",
+        "render_region": list(region),
+        "render_figure": render_stats,
+        "blueprint_figure": blueprint_stats,
+        "aspect_delta": delta(render_stats["aspect"], blueprint_stats["aspect"]),
+        "fill_delta": delta(render_stats["fill"], blueprint_stats["fill"]),
+        "coverage_delta": delta(render_stats["coverage"], blueprint_stats["coverage"]),
+        "mean_lab_render": lab_render,
+        "mean_lab_blueprint": lab_blueprint,
+        "mean_delta_e": mean_de,
+        "palette_render": palette_render,
+        "palette_blueprint": palette_blueprint,
+        "palette_delta_e": palette_delta_e(palette_render, palette_blueprint),
+    }
+
+    if montage_path:
+        report["montage"] = write_montage(render, render_mask, blueprint, blueprint_mask,
+                                          montage_path)
+    return report
+
+
+def write_montage(render, render_mask, blueprint, blueprint_mask, path, height=640):
+    """Render crop and blueprint crop side by side, same height, for a human look."""
+    def crop(image, mask):
+        box = mask.getbbox()
+        return image.crop(box) if box else image
+
+    left = crop(render, render_mask)
+    right = crop(blueprint, blueprint_mask)
+    left = left.resize((max(1, int(left.width * height / max(1, left.height))), height))
+    right = right.resize((max(1, int(right.width * height / max(1, right.height))), height))
+    sheet = Image.new("RGB", (left.width + right.width + 12, height), (20, 20, 20))
+    sheet.paste(left, (0, 0))
+    sheet.paste(right, (left.width + 12, 0))
+    os.makedirs(os.path.dirname(os.path.abspath(path)) or ".", exist_ok=True)
+    sheet.save(path)
+    return os.path.abspath(path)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--render", required=True)
+    ap.add_argument("--blueprint", required=True)
+    ap.add_argument("--out", default="/tmp/gigline/character-match.json")
+    ap.add_argument("--montage", default=None)
+    ap.add_argument("--render-box", default=None,
+                    help="figure box as x0,y0,x1,y1 fractions of the frame (default: central 70 percent)")
+    args = ap.parse_args(argv)
+
+    for path in (args.render, args.blueprint):
+        if not os.path.exists(path):
+            print(f"error: no such image: {path}", file=sys.stderr)
+            return 2
+
+    box = None
+    if args.render_box:
+        box = tuple(float(v) for v in args.render_box.split(","))
+        if len(box) != 4:
+            print("error: --render-box needs four comma-separated fractions", file=sys.stderr)
+            return 2
+    report = evaluate(args.render, args.blueprint, args.montage, box)
+    os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True)
+    with open(args.out, "w") as handle:
+        json.dump(report, handle, indent=2)
+
+    def show(value, digits=3):
+        return "n/a" if value is None or (isinstance(value, float) and math.isnan(value)) \
+            else f"{value:.{digits}f}"
+
+    print(f"render   {report['render_figure']}")
+    print(f"blueprint {report['blueprint_figure']}")
+    print(f"aspect delta    {show(report['aspect_delta'])}")
+    print(f"fill delta      {show(report['fill_delta'])}")
+    print(f"coverage delta  {show(report['coverage_delta'])}")
+    print(f"mean deltaE     {show(report['mean_delta_e'], 1)}")
+    print(f"palette deltaE  {show(report['palette_delta_e'], 1)}")
+    print(f"report -> {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Generate character blueprints with the local ComfyUI instance.
+
+A "blueprint" here is an art-direction sheet for one character: a front, side and back
+view, plus a head detail, generated from a fixed prompt and seed set so the sheet can
+be regenerated and compared against later. It is the reference the modelled character
+is evaluated against — see `Tools/character_match.py`.
+
+    python3 Tools/comfyui_character_blueprint.py \
+        --character "GigLine walker" \
+        --desc "lean adult pedestrian, short dark hair, olive skin, plain navy t-shirt, dark jeans, worn sneakers" \
+        --out Art/characters/blueprints
+
+Writes one PNG per view plus `contact-sheet.png` and `blueprint.json`, which records
+the prompt, model, seeds and the ComfyUI prompt ids. Everything is generated locally
+by `Tools/comfyui_generate.py`; no network service and no credential is involved.
+
+The sheet is generated art, not photography, and it stays out of the reference photo
+folders on purpose: AGENTS.md forbids committing reference photography, and a
+generated concept should not blur that line.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import comfyui_generate as comfy  # noqa: E402
+
+from PIL import Image  # noqa: E402
+
+VIEWS = (
+    # name, prompt suffix, seed
+    ("front", "full body front view, neutral standing pose, arms at sides, "
+              "even studio light, plain light grey background, character sheet", 101),
+    ("side", "full body side profile view, neutral standing pose, arms at sides, "
+             "even studio light, plain light grey background, character sheet", 202),
+    ("back", "full body back view, neutral standing pose, arms at sides, "
+             "even studio light, plain light grey background, character sheet", 303),
+    ("head", "head and shoulders portrait, front view, neutral expression, "
+             "even studio light, plain light grey background", 404),
+)
+NEGATIVE = ("multiple people, crowd, text, watermark, signature, blurry, low quality, "
+            "cropped limbs, extra limbs, deformed hands, cartoon, anime, logo")
+
+
+def contact_sheet(paths, out_path, columns=4):
+    images = [Image.open(p).convert("RGB") for p in paths if os.path.exists(p)]
+    if not images:
+        return None
+    width = max(i.width for i in images)
+    height = max(i.height for i in images)
+    sheet = Image.new("RGB", (width * columns, height), (24, 24, 24))
+    for index, image in enumerate(images[:columns]):
+        sheet.paste(image.resize((width, height)), (index * width, 0))
+    sheet.save(out_path)
+    return out_path
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--character", default="GigLine walker")
+    ap.add_argument("--desc", required=True,
+                    help="what the character wears and looks like; drives every view")
+    ap.add_argument("--out", default="Art/characters/blueprints")
+    ap.add_argument("--model", default=comfy.DEFAULT_MODEL)
+    ap.add_argument("--size", default="832x1216")
+    ap.add_argument("--steps", type=int, default=30)
+    ap.add_argument("--cfg", type=float, default=5.0)
+    args = ap.parse_args(argv)
+
+    if not os.path.isdir(comfy.HOST) and "://" not in comfy.HOST:
+        print(f"error: bad COMFYUI_HOST {comfy.HOST}", file=sys.stderr)
+        return 2
+
+    os.makedirs(args.out, exist_ok=True)
+    width, height = (int(v) for v in args.size.lower().split("x"))
+
+    record = {"character": args.character, "description": args.desc,
+              "model": args.model, "views": {}}
+    written = []
+    for name, suffix, seed in VIEWS:
+        prompt = f"{args.character}, {args.desc}, {suffix}"
+        out = os.path.join(args.out, f"{name}.png")
+        graph = comfy.workflow(prompt, NEGATIVE, args.model, width, height, seed,
+                               args.steps, args.cfg, "dpmpp_2m", "karras")
+        queued = comfy.post("/prompt", {"prompt": graph})
+        prompt_id = queued.get("prompt_id")
+        if not prompt_id:
+            print(f"error: ComfyUI rejected the {name} prompt: {queued}", file=sys.stderr)
+            return 1
+        print(f"{name}: queued {prompt_id} (seed {seed})")
+        image = comfy.wait_for_image(prompt_id, timeout=600.0)
+        if image is None:
+            print(f"error: no image for {name}", file=sys.stderr)
+            return 1
+        with open(out, "wb") as handle:
+            handle.write(image)
+        record["views"][name] = {"file": out, "seed": seed, "prompt": prompt,
+                                 "negative": NEGATIVE, "prompt_id": prompt_id}
+        written.append(out)
+
+    sheet = contact_sheet(written, os.path.join(args.out, "contact-sheet.png"))
+    record["contact_sheet"] = sheet
+    record["note"] = ("generated locally by Tools/comfyui_character_blueprint.py; "
+                      "record the model licence in THIRD_PARTY_NOTICES.md before shipping")
+    with open(os.path.join(args.out, "blueprint.json"), "w") as handle:
+        json.dump(record, handle, indent=2)
+    print(f"wrote {len(written)} views + contact sheet -> {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Generate image assets from the local ComfyUI instance.
+
+The project needs textures it cannot photograph: skin detail, hair strands, fabric
+and surface grime. ComfyUI runs locally at `127.0.0.1:8188`, so this is a
+**human-triggered local tool**, not a network service — nothing in CI calls it, and
+no credential is involved.
+
+    # what is installed
+    python3 Tools/comfyui_generate.py models
+
+    # one image
+    python3 Tools/comfyui_generate.py txt2img \
+        --prompt "seamless photoreal human skin texture, fine pores, neutral light" \
+        --negative "text, watermark, hair, clothing" \
+        --model juggernautXL_ragnarok.safetensors \
+        --size 1024x1024 --seed 7 \
+        --out Art/textures/generated/T_Character_SkinDetail.png
+
+Outputs land in the given path and a JSON sidecar records the exact prompt, model,
+seed and workflow, so an asset can be regenerated or rejected later without
+guessing how it was made.
+
+Licence: the output is a generated image from a locally hosted model. `THIRD_PARTY
+NOTICES.md` must record the model and its licence before the texture ships; the
+sidecar carries what is needed to do that.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+HOST = os.environ.get("COMFYUI_HOST", "http://127.0.0.1:8188")
+DEFAULT_MODEL = "juggernautXL_ragnarok.safetensors"
+
+
+def api(path: str) -> dict:
+    with urllib.request.urlopen(f"{HOST}{path}", timeout=30) as response:
+        return json.loads(response.read().decode())
+
+
+def post(path: str, body: dict) -> dict:
+    request = urllib.request.Request(
+        f"{HOST}{path}", data=json.dumps(body).encode(), method="POST",
+        headers={"Content-Type": "application/json"})
+    with urllib.request.urlopen(request, timeout=60) as response:
+        raw = response.read().decode()
+        return json.loads(raw) if raw.strip() else {}
+
+
+def checkpoints() -> list[str]:
+    info = api("/object_info/CheckpointLoaderSimple")
+    return info["CheckpointLoaderSimple"]["input"]["required"]["ckpt_name"][0]
+
+
+def workflow(prompt: str, negative: str, model: str, width: int, height: int,
+             seed: int, steps: int, cfg: float, sampler: str, scheduler: str) -> dict:
+    """A minimal SDXL/SD1.5 txt2img graph in ComfyUI's API format.
+
+    Node ids are strings and references are `[node_id, output_index]`, which is the
+    format `/prompt` expects — the UI's workflow JSON is a different shape and cannot
+    be posted directly.
+    """
+    return {
+        "1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": model}},
+        "2": {"class_type": "CLIPTextEncode",
+              "inputs": {"text": prompt, "clip": ["1", 1]}},
+        "3": {"class_type": "CLIPTextEncode",
+              "inputs": {"text": negative, "clip": ["1", 1]}},
+        "4": {"class_type": "EmptyLatentImage",
+              "inputs": {"width": width, "height": height, "batch_size": 1}},
+        "5": {"class_type": "KSampler",
+              "inputs": {"seed": seed, "steps": steps, "cfg": cfg,
+                         "sampler_name": sampler, "scheduler": scheduler,
+                         "denoise": 1.0, "model": ["1", 0],
+                         "positive": ["2", 0], "negative": ["3", 0],
+                         "latent_image": ["4", 0]}},
+        "6": {"class_type": "VAEDecode", "inputs": {"samples": ["5", 0], "vae": ["1", 2]}},
+        "7": {"class_type": "SaveImage",
+              "inputs": {"images": ["6", 0], "filename_prefix": "gigline"}},
+    }
+
+
+def wait_for_image(prompt_id: str, timeout: float = 300.0, poll: float = 1.5):
+    """Poll /history until the job has an image, then fetch its bytes."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        history = api(f"/history/{prompt_id}")
+        entry = history.get(prompt_id)
+        if entry and entry.get("outputs"):
+            images = []
+            for node in entry["outputs"].values():
+                images.extend(node.get("images", []))
+            if not images:
+                return None
+            image = images[0]
+            query = urllib.parse.urlencode({
+                "filename": image["filename"],
+                "subfolder": image.get("subfolder", ""),
+                "type": image.get("type", "output")})
+            with urllib.request.urlopen(f"{HOST}/view?{query}", timeout=60) as response:
+                return response.read()
+        time.sleep(poll)
+    return None
+
+
+def generate(args) -> int:
+    width, height = (int(v) for v in args.size.lower().split("x"))
+    seed = args.seed if args.seed is not None else random.randrange(0, 2**31)
+    graph = workflow(args.prompt, args.negative, args.model, width, height, seed,
+                     args.steps, args.cfg, args.sampler, args.scheduler)
+    queued = post("/prompt", {"prompt": graph})
+    prompt_id = queued.get("prompt_id")
+    if not prompt_id:
+        print(f"error: ComfyUI rejected the prompt: {queued}", file=sys.stderr)
+        return 1
+    print(f"queued {prompt_id} ({args.model}, {width}x{height}, seed {seed})")
+
+    data = wait_for_image(prompt_id, timeout=args.timeout, poll=args.poll)
+    if data is None:
+        print("error: no image came back (timeout or empty job)", file=sys.stderr)
+        return 1
+    os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True)
+    with open(args.out, "wb") as handle:
+        handle.write(data)
+    sidecar = os.path.splitext(args.out)[0] + ".json"
+    with open(sidecar, "w") as handle:
+        json.dump({
+            "tool": "Tools/comfyui_generate.py",
+            "generated_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "prompt": args.prompt,
+            "negative": args.negative,
+            "model": args.model,
+            "size": [width, height],
+            "seed": seed,
+            "steps": args.steps,
+            "cfg": args.cfg,
+            "sampler": args.sampler,
+            "scheduler": args.scheduler,
+            "workflow": graph,
+            "comfyui_prompt_id": prompt_id,
+            "note": "generated locally; record the model licence in "
+                    "THIRD_PARTY_NOTICES.md before shipping",
+        }, handle, indent=2)
+    print(f"wrote {args.out} (+ sidecar)")
+    return 0
+
+
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("models", help="list installed checkpoints")
+    t = sub.add_parser("txt2img", help="generate one image")
+    t.add_argument("--prompt", required=True)
+    t.add_argument("--negative", default="text, watermark, signature, blurry, low quality")
+    t.add_argument("--model", default=DEFAULT_MODEL)
+    t.add_argument("--size", default="1024x1024")
+    t.add_argument("--seed", type=int, default=None)
+    t.add_argument("--steps", type=int, default=28)
+    t.add_argument("--cfg", type=float, default=5.5)
+    t.add_argument("--sampler", default="dpmpp_2m")
+    t.add_argument("--scheduler", default="karras")
+    t.add_argument("--out", required=True)
+    t.add_argument("--timeout", type=float, default=300.0)
+    t.add_argument("--poll", type=float, default=1.5)
+    args = ap.parse_args(argv)
+
+    if args.cmd == "models":
+        for name in checkpoints():
+            print(name)
+        return 0
+    return generate(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Procedural character textures: skin detail and hair strands.
+
+The local ComfyUI instance was tried first for skin, and failed in a way worth
+recording: every "flat skin swatch" prompt produced an anatomical body part, twice
+out of three attempts, and the third produced a leather-scale surface. SDXL has no
+useful notion of "texture swatch without anatomy", and a character texture that
+needs manual rejection on every seed is worse than noise we control.
+
+So skin detail is generated here instead: fine tileable noise with a low-frequency
+break-up, which is what the base colour actually needs (pores, not a pattern). Hair
+is generated as a strand sheet with alpha, for hair cards.
+
+    python3 Tools/generate_character_textures.py --out Art/textures/generated
+"""
+
+import argparse
+import json
+import math
+import os
+import random
+import struct
+import zlib
+
+SKIN = {
+    "name": "T_Character_SkinDetail",
+    "size": 512,
+    # Base tone sits near the material's measured skin albedo so a multiply blend
+    # keeps the character's colour rather than tinting it.
+    "tint": (222, 178, 152),
+    "detail": 9,
+}
+
+HAIR = {
+    "name": "T_Character_Hair",
+    "size": 512,
+    "base": (44, 32, 26),
+    "highlight": (96, 74, 58),
+    "strands": 190,
+}
+
+
+def write_png(path, width, height, pixels, alpha=True):
+    """Write RGBA or RGB pixels with zlib, no image library needed."""
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        start = y * width * (4 if alpha else 3)
+        step = 4 if alpha else 3
+        for x in range(width):
+            i = start + x * step
+            raw += pixels[i:i + step]
+
+    def chunk(tag, data):
+        return (struct.pack(">I", len(data)) + tag + data +
+                struct.pack(">I", zlib.crc32(tag + data) & 0xffffffff))
+
+    colour_type = 6 if alpha else 2
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, colour_type, 0, 0, 0)
+    png = b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr)
+    png += chunk(b"IDAT", zlib.compress(bytes(raw), 6)) + chunk(b"IEND", b"")
+    with open(path, "wb") as handle:
+        handle.write(png)
+
+
+def value_noise(size, cells, seed):
+    """Tileable value noise: a lattice that wraps, bilinearly interpolated."""
+    rnd = random.Random(seed)
+    lattice = [[rnd.random() for _ in range(cells)] for _ in range(cells)]
+    out = [0.0] * (size * size)
+    for y in range(size):
+        fy = y / size * cells
+        y0 = int(fy) % cells
+        y1 = (y0 + 1) % cells
+        ty = fy - int(fy)
+        ty = ty * ty * (3 - 2 * ty)
+        for x in range(size):
+            fx = x / size * cells
+            x0 = int(fx) % cells
+            x1 = (x0 + 1) % cells
+            tx = fx - int(fx)
+            tx = tx * tx * (3 - 2 * tx)
+            a = lattice[y0][x0] * (1 - tx) + lattice[y0][x1] * tx
+            b = lattice[y1][x0] * (1 - tx) + lattice[y1][x1] * tx
+            out[y * size + x] = a * (1 - ty) + b * ty
+    return out
+
+
+def skin_texture(spec, out_dir):
+    size, tint, detail = spec["size"], spec["tint"], spec["detail"]
+    # Three octaves: fine pores, mid break-up, broad blotch. All tileable.
+    fine = value_noise(size, 96, 7)
+    mid = value_noise(size, 24, 13)
+    broad = value_noise(size, 7, 21)
+    px = bytearray(size * size * 3)
+    for i in range(size * size):
+        n = (fine[i] - 0.5) * detail * 1.0 + (mid[i] - 0.5) * detail * 0.6 + (broad[i] - 0.5) * detail * 0.4
+        for c in range(3):
+            v = tint[c] + n
+            px[i * 3 + c] = max(0, min(255, int(v)))
+    path = os.path.join(out_dir, spec["name"] + ".png")
+    write_png(path, size, size, px, alpha=False)
+    return path, {"octaves": {"fine": 96, "mid": 24, "broad": 7}, "detail": detail, "tint": tint}
+
+
+def hair_texture(spec, out_dir):
+    size = spec["size"]
+    base, hi = spec["base"], spec["highlight"]
+    rnd = random.Random(5)
+    px = bytearray(size * size * 4)
+    # Vertical strands: each is a line with slight wander, alpha fading at the edges.
+    strands = []
+    for _ in range(spec["strands"]):
+        strands.append({
+            "x": rnd.uniform(0, size),
+            "w": rnd.uniform(0.6, 2.2),
+            "a": rnd.uniform(0.35, 0.95),
+            "wander": rnd.uniform(2.0, 9.0),
+            "phase": rnd.uniform(0, math.tau),
+            "bright": rnd.random(),
+        })
+    for y in range(size):
+        for x in range(size):
+            i = (y * size + x) * 4
+            alpha = 0.0
+            lift = 0.0
+            for s in strands:
+                sx = (s["x"] + math.sin(y / size * math.tau + s["phase"]) * s["wander"]) % size
+                d = abs(x - sx)
+                d = min(d, size - d)
+                if d < s["w"]:
+                    a = (1.0 - d / s["w"]) * s["a"]
+                    if a > alpha:
+                        alpha = a
+                        lift = s["bright"]
+            if alpha <= 0.02:
+                px[i:i + 4] = bytes((0, 0, 0, 0))
+                continue
+            shade = [base[c] + (hi[c] - base[c]) * lift for c in range(3)]
+            px[i:i + 3] = bytes(max(0, min(255, int(v))) for v in shade)
+            px[i + 3] = int(min(1.0, alpha) * 255)
+    path = os.path.join(out_dir, spec["name"] + ".png")
+    write_png(path, size, size, px, alpha=True)
+    return path, {"strands": spec["strands"], "base": base, "highlight": hi}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", default="Art/textures/generated")
+    args = ap.parse_args()
+    os.makedirs(args.out, exist_ok=True)
+    results = {}
+    for spec, maker in ((SKIN, skin_texture), (HAIR, hair_texture)):
+        path, meta = maker(spec, args.out)
+        sidecar = os.path.splitext(path)[0] + ".json"
+        with open(sidecar, "w") as handle:
+            json.dump({"tool": "Tools/generate_character_textures.py",
+                       "asset": spec["name"], "size": spec["size"],
+                       "procedural": True, "meta": meta,
+                       "note": "generated, not photographed; no third-party licence"},
+                      handle, indent=2)
+        results[spec["name"]] = path
+        print(f"wrote {path} (+ sidecar)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,82 @@
+"""Tests for the pure parts of Tools/character_match.py."""
+
+import os
+import sys
+import unittest
+
+from PIL import Image
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+import character_match as cm  # noqa: E402
+
+
+class ColourTests(unittest.TestCase):
+    def test_white_is_light_and_neutral(self):
+        light, a, b = cm.rgb_to_lab((255, 255, 255))
+        self.assertAlmostEqual(light, 100.0, delta=0.2)
+        self.assertAlmostEqual(a, 0.0, delta=0.2)
+        self.assertAlmostEqual(b, 0.0, delta=0.2)
+
+    def test_black_is_dark(self):
+        self.assertAlmostEqual(cm.rgb_to_lab((0, 0, 0))[0], 0.0, delta=0.1)
+
+    def test_identical_colours_have_no_distance(self):
+        self.assertAlmostEqual(cm.delta_e76(cm.rgb_to_lab((120, 90, 70)),
+                                           cm.rgb_to_lab((120, 90, 70))), 0.0, delta=1e-9)
+
+    def test_red_green_are_far_apart(self):
+        distance = cm.delta_e76(cm.rgb_to_lab((200, 40, 40)), cm.rgb_to_lab((40, 160, 40)))
+        self.assertGreater(distance, 40.0)
+
+
+class MaskTests(unittest.TestCase):
+    def _image(self, figure_colour, background_colour):
+        image = Image.new("RGB", (60, 100), background_colour)
+        pixels = image.load()
+        for y in range(20, 90):
+            for x in range(25, 35):
+                pixels[x, y] = figure_colour
+        return image
+
+    def test_saturated_figure_on_grey_is_found(self):
+        mask = cm._subject_mask(self._image((150, 90, 60), (190, 190, 190)))
+        box = cm.bbox(mask)
+        self.assertIsNotNone(box)
+        self.assertLess(box[0], 30)
+        self.assertGreater(box[2], 30)
+
+    def test_grey_frame_yields_empty_mask(self):
+        mask = cm._subject_mask(self._image((190, 190, 190), (190, 190, 190)))
+        self.assertIsNone(cm.bbox(mask))
+
+    def test_stats_report_figure_proportions(self):
+        mask = Image.new("L", (40, 80), 0)
+        pixels = mask.load()
+        for y in range(10, 70):
+            for x in range(15, 25):
+                pixels[x, y] = 255
+        stats = cm.mask_stats(mask)
+        self.assertEqual(stats["area"], 600)
+        self.assertAlmostEqual(stats["aspect"], 6.0, delta=0.01)
+        self.assertAlmostEqual(stats["fill"], 1.0, delta=0.01)
+
+
+class PaletteTests(unittest.TestCase):
+    def test_dominant_colour_is_reported(self):
+        colours = [(200, 40, 40)] * 90 + [(20, 60, 200)] * 10
+        palette = cm.dominant(colours, count=2)
+        self.assertEqual(len(palette), 2)
+        red, _, _ = cm.rgb_to_lab(palette[0])
+        self.assertGreater(red, 30.0)
+
+    def test_palette_distance_is_zero_for_the_same_palette(self):
+        palette = cm.dominant([(200, 40, 40)] * 50)
+        self.assertAlmostEqual(cm.palette_delta_e(palette, palette), 0.0, delta=1e-6)
+
+    def test_empty_palette_is_not_a_number(self):
+        self.assertNotEqual(cm.palette_delta_e([], [(1, 2, 3)]),
+                            cm.palette_delta_e([], [(1, 2, 3)]))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -322,7 +322,7 @@ def build():
    # 3. Ambience. A height fog gives the street depth and hides the terrain
    #    edge that otherwise reads as a black band at the horizon.
    sun = spawn(unreal.DirectionalLight, unreal.Vector(0, 0, 2000), "Demo_Sun",
-                unreal.Rotator(pitch=-62.0, yaw=120.0, roll=0.0))
+                unreal.Rotator(pitch=-74.0, yaw=120.0, roll=0.0))
    if sun:
        comp = sun.get_component_by_class(unreal.DirectionalLightComponent)
        if comp:
@@ -341,7 +341,7 @@ def build():
                comp.set_mobility(unreal.ComponentMobility.MOVABLE)
            except Exception as exc:  # noqa: BLE001
                log(f"sun mobility not set: {exc!r}")
-        log("staged: Demo_Sun (pitch -62, yaw 120, intensity 4, warm; higher sun so both frontages read)")
+        log("staged: Demo_Sun (pitch -74, yaw 120, intensity 4, warm; higher sun lifts the north sidewalk out of building shadow)")

    sky = spawn(unreal.SkyLight, unreal.Vector(0, 0, 2000), "Demo_SkyLight")
    if sky:
@@ -19,7 +19,7 @@ import unreal

 SRC = "/tmp/gigline/character-anim.fbx"
 DEST = "/Game/Test/Character"
-PREFIX = "CharacterV2"
+PREFIX = "CharacterV6"
 RESULT = "/tmp/gigline/character-anim-import.txt"
 lines = []

@@ -0,0 +1,71 @@
+# Import the garment meshes as separate skeletal meshes (0.2.2).
+#
+#   blender -b Art/blender/character/character-2026-11-07.blend \
+#       --python Tools/character_clothing_build.py -- --out /tmp/gigline/clothing
+#   <engine>/Engine/Binaries/Linux/UnrealEditor-Cmd <uproject> -run=pythonscript \
+#     -script=<repo>/Tools/ue_character_clothing_import.py -nullrhi -unattended -nopause -stdout
+#
+# Each garment is its own asset, per the character-artist skill's rule that clothing
+# stays separate so it can be swapped or re-materialled. The pawn attaches each one as
+# a component using the body as the leader pose.
+#
+# Result file: /tmp/gigline/character-clothing-import.txt
+
+import unreal
+
+DEST = "/Game/Test/Character"
+SOURCE = "/tmp/gigline/clothing"
+GARMENTS = (("tee", "CharacterTee"), ("jeans", "CharacterJeans"), ("shoes", "CharacterShoes"))
+RESULT = "/tmp/gigline/character-clothing-import.txt"
+lines = []
+
+
+def log(msg):
+    lines.append(str(msg))
+    unreal.log(str(msg))
+
+
+def main():
+    for source, name in GARMENTS:
+        task = unreal.AssetImportTask()
+        task.filename = f"{SOURCE}/{source}.fbx"
+        task.destination_path = DEST
+        task.destination_name = name
+        task.automated = True
+        task.save = True
+        task.replace_existing = True
+
+        ui = unreal.FbxImportUI()
+        ui.import_mesh = True
+        ui.import_as_skeletal = True
+        ui.import_animations = False
+        ui.import_materials = True
+        ui.import_textures = False
+        ui.skeletal_mesh_import_data.import_uniform_scale = 1.0
+        task.options = ui
+        unreal.AssetToolsHelpers.get_asset_tools().import_asset_tasks([task])
+
+        mesh = unreal.EditorAssetLibrary.load_asset(f"{DEST}/{name}")
+        if mesh is None:
+            log(f"{name}: MISSING after import")
+            lines.append("VERDICT: FAIL")
+            return
+        mats = mesh.get_editor_property("materials")
+        log(f"{name}: imported, {len(mats)} slot(s): "
+            + ", ".join((m.get_editor_property("material_interface").get_name()
+                         if m.get_editor_property("material_interface") else "None")
+                        for m in mats))
+    lines.append("VERDICT: PASS")
+
+
+try:
+    main()
+except Exception as exc:  # noqa: BLE001
+    import traceback
+    log(f"FAILED: {type(exc).__name__}: {exc}")
+    log(traceback.format_exc())
+    lines.append("VERDICT: FAIL")
+
+unreal.EditorLoadingAndSavingUtils.save_dirty_packages(True, True)
+with open(RESULT, "w") as f:
+    f.write("\n".join(lines) + "\n")
Author	SHA1	Message	Date
zwitschi	82cafc2f29	fix(camera): prove the boom shortens, and record how to repeat it With the spring arm activated the collision now works: a 2 m wall spawned 4 m behind the pawn shortens the boom from 340 cm to 288 cm - 12 cm clear of the wall, matching the probe size. -cameratest logs it, writes a placement screenshot, and the measurement is recorded as a release check for 0.2.3. Two traps documented because each one made a working mechanism look broken: - a spawned static-mesh actor has no collision unless it is created deferred and given its mesh and collision before FinishSpawning (three runs reported blocks trace=0) - TargetArmLength is not rewritten when the boom shortens, so reading the property reports the requested length; the camera's distance from the head is the measurement Writes the 0.2.3 changelog entry and prunes the section from TODO.md.	2026-11-09 14:40:18 +01:00
zwitschi	3e4dbd1014	fix(camera): activate the spring arm with the third-person rig Real defect, found by reading the code rather than by the harness: the spring arm was created with SetAutoActivate(false), and ToggleCamera only activated the camera. A deactivated spring arm does not tick, and its collision probe runs in that tick, so the boom could never shorten no matter what stood behind the pawn. ToggleCamera and BeginPlay now activate the arm alongside the camera. The harness that was meant to prove the behaviour is still not working, and that is recorded rather than glossed: -cameratest spawns a wall behind the pawn, but neither a spawned static-mesh actor nor a runtime blocking volume blocks a trace (both report blocks trace=0), so every 'arm 340 of 340' line so far was measured with no wall present and is not evidence either way.	2026-11-09 14:37:03 +01:00
zwitschi	a6701aa3d1	test(camera): -cameratest harness for the spring-arm collision, result inconclusive 0.2.3 is about camera clipping, and nothing had ever exercised the spring arm's collision test. This adds a harness: find the nearest wall from the spawn, stand the pawn 70 cm off it facing away, wait for the boom, then report the arm length, whether the boom ends inside geometry, and a back-trace from camera to head. Inconclusive, and the setup is the suspect rather than the engine: every run reports the arm at its resting 340 cm, but BOTH traces come back clear, so nothing was between the pawn and the boom at all. The placement is wrong, not necessarily the collision. Three wrong turns recorded in TODO.md because each cost a run: the probe accepted the floor as a wall, then faced the pawn into the wall by negating the impact normal (which points away from it), then set actor rotation only - which a possessed pawn discards in favour of control rotation. Next: look at the placement screenshot before trusting the measurement.	2026-11-09 14:33:57 +01:00
zwitschi	d8b44f1e57	Merge pull request #36 : v0.2.2 — the character pass Clothing, hair cards, character blueprints and render-vs-blueprint comparison, raised sun, walk cycle starting at maximum stride. All eight review shots approved.	2026-11-09 14:26:22 +01:00
zwitschi	6c4e0701fb	release: v0.2.2 — the character pass Writes the 0.2.2 entry and prunes the section from TODO.md. The entry records that this ships as a patch by the owner's decision even though it adds asset categories, which the policy otherwise puts in a minor release - so the numbering is not mistaken for scope. Contents: clothing as three separate skinned meshes, hair cards oriented from the scalp normal, ComfyUI character blueprints and the render-vs-blueprint comparison, procedural textures, materials built from scratch, the raised sun, and the walk cycle starting at maximum stride. Verified: 8/8 shots, all approved; mean deltaE 31.9 -> 21.8 against the blueprint; 95 tool tests. Known limitations listed rather than omitted - garments are shells over body faces, the baked diffuse cannot be used because the mesh UVs do not map to it, and the character has no face detail.	2026-11-09 14:26:13 +01:00
zwitschi	0e7a6e898b	docs(review): owner approved shots 6, 7 and 8 — all eight shots approved Ticks both the shot sections and their status rows, so the table and the sections agree: 5 previously approved, these 3 approved 2026-11-09 in their clothed, haired, relit state.	2026-11-09 14:25:35 +01:00
zwitschi	2f6d06f897	docs(review): restore the status rows for shots 7 and 8 The previous documentation commit dropped both rows from the status table while editing the section text - the table then listed six shots against eight embeds. Restored, both marked verified and pending approval.	2026-11-09 14:24:02 +01:00
zwitschi	5de4183456	docs(review): shots 6, 7 and 8 reflect the clothed, haired character The appearance changed in 0.2.2 and the README still described an unclothed body with splayed fingers, which is a defect in its own right: a shot whose README section is stale is not a review. Shots 6, 7 and 8 now describe the clothing, the dark card hair and the raised sun, and their approvals are reset to pending because the appearance changed. 8/8 shots verify.	2026-11-09 14:23:47 +01:00
zwitschi	bea6aa3e05	light: raise the sun so the character leaves building shadow (needs approval) The skin was never grey. A red test colour reached the render and the slot was confirmed holding M_Character_Skin, so the material and the assignment were both fine - the body was simply standing in building shadow and lit almost entirely by the blue skylight (intensity 2.6). Warm skin under blue fill reads blue-grey. Raising the sun from pitch -62 to -74, same camera: face (99, 98, 100) -> (131, 121, 117) arms (67, 74, 81) -> (71, 78, 85) This touches every approved shot, so it sits on the branch for the owner's approval rather than being folded in. Also records that the Unreal commandlet silently drops unknown switches, which is why a --unlit-test flag never took effect.	2026-11-09 14:20:07 +01:00
zwitschi	7c57bf318b	fix(hair): dark constant colour, strand sheet used only as an opacity mask The hair read blond and thin because the strand sheet's RGB was driving base colour; the sheet is a pale highlight map. Colour is now a dark constant (0.030/0.020/0.014) and the texture supplies only alpha. Sampled in the render: hair (31, 26, 21). Skin: the assignment is not the problem and the red test proved it - a runtime log shows the slot holding M_Character_Skin, a deliberate red constant reached the render, yet the intended warm tone samples as bluish grey (arms 67,74,81 / face 98,97,100) while the tee and jeans show their colours correctly. Recorded in TODO.md with the next suspects rather than guessed at. The temporary material log is removed again.	2026-11-09 13:55:19 +01:00
zwitschi	878d5a1f4e	fix(clothing): close the coverage holes, and bind materials without crashing Solidify thickness went from 1 cm to 2 cm and the shell is fattened 8 mm along its own normals afterwards. That closed the shoulders, hips and knees where the body was showing through the cloth. Evaluation against the blueprint, same shot and box before and after: mean deltaE 31.9 -> 21.8 palette deltaE 25.4 -> 19.7 aspect delta 1.24 -> 1.22 Also fixes a crash I introduced: binding the materials in Tick used ConstructorHelpers::FObjectFinder, which is fatal outside a constructor - the game died with 'FObjectFinders can't be used outside of constructors' and the render run failed with signal 11. The binding now lives in BeginPlay and uses LoadObject. Not fixed, and recorded: the arms and face still render neutral grey, so M_Character_Skin itself is suspect rather than the assignment.	2026-11-09 13:50:21 +01:00
zwitschi	86e9c5b693	feat(clothing): tee, jeans and shoes as separate skinned meshes Follows the character-artist clothing workflow literally: duplicate the body's own faces for the garment base, solidify for cloth thickness, and keep each piece a separate mesh. Attached as leader-pose components beside the hair, so no second rig. - Tools/character_clothing_build.py builds three garments from the body mesh, trimmed geometrically (height band plus a width limit) instead of by dominant bone: the bone filter left holes wherever a face's strongest bone was outside the allowed list. - Tools/ue_character_clothing_import.py imports them as CharacterTee / CharacterJeans / CharacterShoes, each arriving with its own single material slot. - The pawn attaches all three, hidden with the body in first person. Three traps recorded in MEMORY.md, each of which cost a build: MPFB weights its helper geometry to groups that dominate every vertex, Blender refuses to apply a modifier to a mesh with shape keys, and object-mode polygon selection is discarded on entering edit mode - the delete wiped the whole garment. Known defects, in TODO.md: the garments have coverage holes at shoulders, hips and knees, and the hair reads light and wispy since its material was repointed to the masked strand sheet.	2026-11-09 13:41:39 +01:00
zwitschi	85a8437cbc	feat(character): ComfyUI blueprints and a render-vs-blueprint evaluation Two tools that turn character work into something measurable. - Tools/comfyui_character_blueprint.py generates a four-view sheet (front, side, back, head) plus a contact sheet from one description, with fixed seeds and a JSON record of prompts and prompt ids. First sheet: 'GigLine walker', lean pedestrian in a navy tee, jeans and sneakers. - Tools/character_match.py compares a rendered character against a sheet: figure aspect, fill and coverage deltas, mean CIE76 colour distance, dominant-palette distance, and a side-by-side montage. The deltas stay separate on purpose - a single similarity score between a photoreal sheet and a low-detail body would be a number with no meaning. - comfyui_generate.py grew wait_for_image() so both tools share the polling path instead of duplicating it. - 13 unit tests for the colour maths, masks and palette; 95 tool tests pass. First real result, recorded rather than smoothed over: aspect delta 1.24, fill delta 0.12, mean deltaE 31.9, palette deltaE 25.4. The montage shows the reason - the model is a nude body and the blueprint wears a tee and jeans, so clothing dominates every metric. Figure segmentation is explicit (--render-box): auto-detection picked backdrop blobs on every attempt, and a background plate is the proper fix.	2026-11-09 13:36:28 +01:00
zwitschi	1fc5835327	fix(hair): cards follow the scalp normal, three overlapping rows The first card build anchored every card on a fixed outward vector, so the silhouette was a spiked crown. Each card is now oriented from the scalp normal at its anchor: the length runs along the downward tangent, the width across it, and a small tip lift gives the cut volume. Three overlapping rows (7/9/10) replace the single ring; overlap is what stops cards reading as separate spikes. 26 cards, 401 verts, 224 quads, 468 tris, still all quads on one head bone. Recorded as still open: the skin renders darker than the baked diffuse suggests, and the generated pore and strand textures remain unwired because the material-editing tool segfaults in the headless commandlet.	2026-11-09 13:25:40 +01:00
zwitschi	39f07b0f5f	feat(hair): hair cards as their own skinned mesh, attached as a second component Follows the character-artist skill on two points it is explicit about: hair for a game character is a card system, and swappable parts stay separate meshes. - Tools/character_hair_build.py builds SM_Char_Hair: a scalp cap plus 18 cards in three rings, quads only, every vertex weighted 1.0 to the head bone, UV-mapped for the strand sheet from Tools/generate_character_textures.py. 321 verts / 404 tris. - Tools/ue_character_hair_import.py imports it as its own skeletal mesh, which is the point: joined into the body, Unreal collapses the second material slot and the hair renders with the skin material. - The pawn carries it as a second USkeletalMeshComponent on SetLeaderPoseComponent, so it follows the head bone with no second rig and hides with the body in first person. Still wrong and recorded: the cards point outward, so the silhouette reads as a spiked crown rather than a short cut. The next pass orients them tangentially along the skull with a second overlapping row. Tools/ue_character_materials.py also segfaults in the headless commandlet when editing a material graph, so the generated textures are not wired yet and the hair keeps its Blender base colour.	2026-11-09 13:18:40 +01:00
zwitschi	72d00bdfbd	memory: ComfyUI API shape, SD's failure on flat swatches, the material-slot collapse	2026-11-09 13:10:57 +01:00
zwitschi	54c579ab1a	feat(tex): ComfyUI tool, procedural character textures, hair cap behind a flag Tools/comfyui_generate.py drives the local ComfyUI instance for generated textures and writes a sidecar with model, prompt, seed and workflow, so a generated asset can be regenerated or rejected instead of being an unexplained PNG. Models list and generation both verified against 127.0.0.1:8188. Stable Diffusion is not usable for flat skin swatches, and that is worth recording: three attempts produced an anatomical close-up twice and a leather-scale surface once. Skin detail is generated procedurally instead - tileable octave noise for pores, plus a strand sheet for hair - in Tools/generate_character_textures.py, with sidecars. Hair geometry exists (cap conforming to the head, weighted to the head bone, second material slot in Blender) but Unreal's import collapses the second material slot, so the cap renders with the skin material and reads as a bald skull. It is behind --hair and off; the next step is a separate skeletal mesh attached as a second component.	2026-11-09 13:09:39 +01:00
zwitschi	89a9c59747	Merge pull request #35 : walk cycle starts at maximum stride The stride shot regression was the clip's phase, not the capture harness: a sine starts and crosses zero at the two frames where the legs pass together.	2026-11-09 13:05:51 +01:00
zwitschi	4b9ad22108	fix(walk): the cycle starts at maximum stride, so the capture shows one The stride shot regressed twice for two different reasons, and only the second was the clip. The walk cycle was authored on a sine, which is zero at both the start and the middle of the cycle - exactly the two frames where the legs pass together - so a deterministic capture at any phase near those frames read as a still. The probe proved it: frames 0 and 15 carried identical hip rotations while 7 and 22 were the stride. The cycle now starts at maximum stride (cosine). Length, amplitudes, keys and loop are unchanged; only the phase moved. demo-third-person-walk is back as shot 8 and shows a genuine stride with the curled hands from 0.2.1. 8/8 shots verify.	2026-11-09 12:55:53 +01:00
zwitschi	0d57b718cf	Merge pull request #34 : 0.2.0 + 0.2.1 — third-person body, animation, rig fixes Third-person body with animated idle/walk, review harness for a deterministic stride capture, F3 debug overlay, and the 0.2.1 rig fixes (curled fingers, derived arm angle).	2026-11-09 12:53:28 +01:00
zwitschi	e9f31f271e	release: v0.2.1 — rig fixes changelog entry, TODO pruning Writes the 0.2.1 entry (fingers, derived arm angle, base keys) and removes the section from TODO.md. The stride-capture regression is listed under known limitations rather than omitted: the shot is retired, not shipped.	2026-11-09 12:52:01 +01:00
zwitschi	03af8146a6	fix(rig): curl the fingers, derive the arm angle Two defects from the 0.2.0 review, both fixed and both measured. - Fingers splayed because the bind is an A-pose hand. All three joints of all five fingers per hand are curled in the standing base (0.28/0.34/0.22 rad), with the curl axis probed on the rig first. The front shot now shows relaxed hands. - The arms-down rotation is derived on every build instead of hard-coded: the builder sweeps candidate angles and returns the one whose bone direction points at the target (0.60 rad, direction dot 1.000 this build). The old 0.55 was a hand-swept constant. - Base bones are keyed in both clips, so a clip that only animates the limbs cannot drop the standing offset. Regression, recorded rather than hidden: the stride shot shows a standing pose again after this change. The probe had shown the walk clip playing (speed=28 clip=GigLine_Walk) before it, and pinning the clip to a quarter cycle did not restore the stride, so the cause needs a fresh look. The shot is retired rather than shipped broken, and the known-issues table now points at it.	2026-11-09 12:48:40 +01:00
zwitschi	30e4d65743	todo: claim 0.2.1 rig fixes — splayed fingers, derived standing pose	2026-11-09 12:43:25 +01:00