(remote viewing) updates to the mc package

MinecraftRenderingNotes.md

@@ -0,0 +1,98 @@
+# Minecraft Rendering Notes
+
+This document tracks the current split vision stack and the historical commit lineage.
+
+Current branch snapshot:
+
+- **Current commit**: `5020512c394d8c4f4b27b93d6f6659cfc16606a0`
+- **Both renderers now exist in the same branch/commit**:
+  - `EntityVision.java`
+  - `WorldVision.java`
+- Runtime selection is currently in `XosViewportRuntime.renderAgentViewRgbaHex(...)` and `flushDeferredVisionCaptures(...)` with an easy comment swap.
+
+---
+
+## 1) Entity Rendering
+
+### What `EntityVision` does now
+
+`EntityVision` is the camera-driven render-pass path intended for accurate POV rendering:
+
+- Per-camera context (`CameraContext`) keyed by agent UUID.
+- Offscreen `TextureTarget` lifecycle management.
+- Render-thread scheduling (`queueCapture` + `flushDeferredCaptures`) so world pass work stays on the correct thread.
+- Capture using actual game render invocation (`renderLevel`) and readback.
+
+Tiny internals example:
+
+```java
+camera.target = new TextureTarget(width, height, true, Minecraft.ON_OSX);
+mc.setCameraEntity(cameraEntity);
+gameRendererRenderLevelMethod.invoke(mc.gameRenderer, args);
+GL11C.glReadPixels(..., GL11C.GL_RGBA, GL11C.GL_UNSIGNED_BYTE, buf);
+```
+
+Why `EntityVision` is the "accurate entity" direction:
+
+- It is camera-entity based (agent POV), not just projected world math.
+- It uses renderer passes rather than hand-authored entity shapes.
+- It keeps per-camera state and deferred capture semantics needed for correctness.
+
+---
+
+## 2) World Rendering
+
+### What `WorldVision` does now (ported from `4c790a70...` lineage)
+
+`WorldVision` keeps the block-state ray/clip approach from the `b30d00d9...` and `4c790a70...` line:
+
+- Per-pixel world ray casting using `ClipContext`.
+- Block color from `MapColor` with registry-hash fallback.
+- Distance and face-based shading for depth/readability.
+- Entity overlay rendered as projected disks (orbs) with depth checks.
+
+Tiny world hit example:
+
+```java
+var hit = mc.level.clip(new ClipContext(origin, rayEnd, OUTLINE, NONE, agent));
+BlockPos bp = hit.getBlockPos();
+int rgb = rgbFromBlockState(mc, bp, state);
+```
+
+Tiny orb overlay example:
+
+```java
+int color = rgbFromEntity(e);
+if ((dx * dx + dy * dy) <= rr && camZ < depth[p]) {
+  // paint projected entity disk
+}
+```
+
+What `WorldVision` gives:
+
+- World **state structure** that is close to live block layout.
+- Stable, readable rendering and predictable performance shape.
+- Explicit fallback behavior that is easy to reason about.
+
+What `WorldVision` does **not** provide:
+
+- Mesh/textured entity rendering.
+- Full native-frame parity with Minecraft's standard on-screen camera pass.
+
+---
+
+## EntityVision vs WorldVision
+
+Both renderers now exist side by side in one branch so each can be stabilized independently.
+
+- **`EntityVision`**
+  - Camera/render-pass architecture (`renderLevel` + offscreen target + readback).
+  - Best path toward true POV fidelity (including proper entity rendering).
+  - More sensitive to render-thread/target-state correctness.
+
+- **`WorldVision`**
+  - Deterministic ray/clip world sampler with shaded block colors.
+  - Entity visibility via synthetic projected orbs.
+  - Easier to reason about for world-state output and debugging.
+
+This split is intentional: verify each path independently, then merge strengths into one robust final renderer.