# Dispatch for Worker M2 (Graphics R&D & Pipeline Optimization)

## Task Objective
Implement the graphics cost-reduction pipeline tools, integration, unit tests, and comprehensive technical research report.

## Input Files
- `c:/Projects/FreeExile/.agents/teamwork/ORIGINAL_REQUEST.md` (specifically 2026-10-01T22:03:34Z)
- `c:/Projects/FreeExile/.agents/teamwork/explorer_survey_pipeline/analysis.md`
- `tools/asset_pipeline/animation_pipeline.py`
- `client/webapp/assets/monsters/monster_palette_instancing.metal`

## Exclusive Write Ownership
- `tools/asset_pipeline/lod_generator.py`
- `tools/asset_pipeline/texture_compressor.py`
- `tools/asset_pipeline/viewport_culling_utils.py`
- `tools/asset_pipeline/mipmap_utils.py`
- `tools/asset_pipeline/animation_pipeline.py`
- `client/webapp/assets/monsters/monster_palette_instancing.metal`
- `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md`
- `tests/unit/test_viewport_culling.py`
- `tests/unit/test_asset_pipeline_tools.py`

## Requirements
1. **LOD Generator (`tools/asset_pipeline/lod_generator.py`)**:
   - Python 3.11+, strict typing.
   - CLI + Python API `generate_sprite_lods(image_path: Path, output_dir: Path | None = None) -> dict[str, Path]`.
   - Generates 3 LOD levels: LOD-0 (100%), LOD-1 (50%), LOD-2 (25%) using Pillow Lanczos.
   - Requirement: LOD-2 file size <= 40% of original.

2. **WebP Texture Compressor (`tools/asset_pipeline/texture_compressor.py`)**:
   - CLI + Python API `compress_to_webp(input_path: Path, output_path: Path | None = None, quality: int = 80) -> CompressionResult`.
   - Batch conversion support for directories.
   - Requirement: WebP output file size <= 50% of original PNG size.

3. **Viewport Culling Utility (`tools/asset_pipeline/viewport_culling_utils.py`)**:
   - Frustum AABB 2D intersection testing for isometric viewport.
   - `class AABB(slots=True, frozen=True)`, `class Frustum2D(slots=True, frozen=True)`.
   - `intersects(frustum: Frustum2D, box: AABB) -> bool`.
   - `cull_entities(camera_pos: tuple[float, float], viewport_size: tuple[float, float], entities: list[EntityBounds]) -> list[EntityBounds]`.
   - Unit tests in `tests/unit/test_viewport_culling.py` covering edge cases, outside, inside, partial overlap. Must pass `pytest tests/unit/test_viewport_culling.py`.

4. **Mipmap Integration (`tools/asset_pipeline/mipmap_utils.py` & `animation_pipeline.py`)**:
   - Create `mipmap_utils.py` to keep `animation_pipeline.py` <= 500 lines!
   - Integrate `--generate-mipmaps` flag or automatic mipmap chain generation in `animation_pipeline.py`.
   - Downsamples power-of-two chains down to 1x1.

5. **Metal Shader Instancing Guidance**:
   - In `client/webapp/assets/monsters/monster_palette_instancing.metal`, add comprehensive GPU instancing architecture guidance and shader kernel support for rendering 200+ monster instances in a single draw call with dynamic buffer offsets and palette LUT lookup.

6. **Technical Research Report (`docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md`)**:
   - Must be >= 300 lines.
   - Contains measured benchmark tables (LOD reduction numbers, WebP compression ratios, culling performance, Metal draw call reductions).
   - Server AoI animation state filtering documentation & pseudocode.
   - Bitmask delta compression architecture (83% bandwidth reduction).
   - Asset manifest HTTP ETag / 304 conditional caching layer design.

7. **Verification**:
   - Run tests: `pytest tests/unit/test_viewport_culling.py` and `pytest tests/unit/test_asset_pipeline_tools.py`.
   - Verify line count caps (`check_code_and_doc_hygiene.py`).

## Output Requirements
Write `progress.md` with timestamps and `handoff.md` in `c:/Projects/FreeExile/.agents/teamwork/worker_m2_rnd/`.
Send message to parent when done.

## 2026-10-01T22:12:12Z
Received dispatch message:
MANDATORY: You MUST read the full user request before starting work at:
c:/Projects/FreeExile/.agents/teamwork/ORIGINAL_REQUEST.md (specifically the latest request under header '## 2026-10-01T22:03:34Z').
Also read your dispatch task at:
c:/Projects/FreeExile/.agents/teamwork/worker_m2_rnd/DISPATCH.md
Also read the technical survey at:
c:/Projects/FreeExile/.agents/teamwork/explorer_survey_pipeline/analysis.md

MANDATORY INTEGRITY WARNING:
DO NOT CHEAT. All implementations must be genuine. DO NOT hardcode test results, create dummy/facade implementations, or circumvent the intended task. A teamwork_preview_auditor will independently verify your work. Integrity violations WILL be detected and your work WILL be rejected.

Your mission:
1. Implement `tools/asset_pipeline/lod_generator.py` (CLI + API, 3 LOD levels 100%, 50%, 25%, LOD-2 <= 40% size).
2. Implement `tools/asset_pipeline/texture_compressor.py` (CLI + API, batch PNG -> WebP <= 50% size).
3. Implement `tools/asset_pipeline/viewport_culling_utils.py` (frustum AABB intersection for isometric entities) and unit tests in `tests/unit/test_viewport_culling.py`.
4. Implement `tools/asset_pipeline/mipmap_utils.py` and wire mipmap generation into `tools/asset_pipeline/animation_pipeline.py` (keep code <= 500 lines!).
5. Add 200+ instance draw call batching guidance in `client/webapp/assets/monsters/monster_palette_instancing.metal`.
6. Write comprehensive technical report `docs/research/RENDERING_OPTIMIZATION_TECH_REPORT.md` (>= 300 lines) with measured benchmarks, AoI filtering, delta compression, and HTTP ETag caching.
7. Run all tests with pytest and verify everything passes.
8. Maintain `progress.md` with timestamps and produce `handoff.md` in your working directory.
9. Send a completion message back to parent with your test and benchmark results.