Files
neoLegacy-mac/WORKLOG.md
2026-07-13 00:00:40 -05:00

207 lines
13 KiB
Markdown

# PRIMARY GOAL (Cole, session 3): NATIVE macOS VULKAN PORT — no Wine
Cole's clarified intent: removing SWF/Iggy + using a UI library + PNGs was
always in service of a NATIVE macOS build running Vulkan (MoltenVK). Wine is
a bridge only. The native port is now the main objective.
## Native port plan (execute in order; keep game logic untouched)
1. New CMake platform "Darwin64": compile Minecraft.World + Minecraft.Client
Common/ natively (arm64, clang). Expect a porting layer for Win32 types:
create `darwin/win32_compat.h` (DWORD/HANDLE/CRITICAL_SECTION→pthread,
Sleep, GetTickCount, wchar handling — the codebase uses wchar_t heavily;
macOS wchar_t is 4-byte vs Windows 2-byte → compile with -fshort-wchar OR
audit; -fshort-wchar breaks system libs, prefer keeping 4-byte and fixing
assumptions).
2. Platform shell: SDL2 (already in CX/lib, or fetch) for window/input/events
replacing Windows64_Minecraft.cpp WinMain/WndProc/KeyboardMouseInput.
3. Renderer: implement the OPEN 4J_Render API (Minecraft.Client/Windows64/
4JLibs/inc/4J_Render.h, impl reference impls/Windows_Libs/Render/) on
Vulkan via MoltenVK (brew molten-vk already installed). ~142 methods but
the game uses a subset; port shaders from HLSL (fxc sources in
4JLibs/impls/Windows_Libs/Render/shaders/*.hlsl) to SPIR-V via dxc or
translate to GLSL.
4. iggy-shim: already portable C++ except raw_d3d.cpp — add a Vulkan quad
renderer variant (or route through the new 4J_Render Vulkan impl).
RmlUi+FreeType compile natively trivially (no cross-compile pain).
5. Audio: miniaudio is native-ready (CoreAudio backend) — zero work expected.
6. Network: Winsock→BSD sockets shim (mostly 1:1; WSAStartup no-ops).
7. Filesystem/saves: lce_filesystem FolderFile — path separators + CreateFile
→fopen mapping.
Deliverable: Minecraft.Client.app (arm64) rendering via Vulkan/MoltenVK.
Start with step 1 and iterate compile errors; the codebase is ~628K LOC but
Common/ is mostly portable C++ with wchar strings.
# UPDATE (session 3): WHITE SCREEN FIXED — runtime is now CrossOver 26
- ROOT CAUSE: wine-crossover 8.0.1 (2023) + DXVK-macOS 1.10.3 present path
composites WHITE on macOS 27 while the backbuffer is correct (F2 captures
always looked right; live window was 97% white pixels).
- FIX: CrossOver 26.0 (wine-11.0). Bottle "neolegacy" created via
`cxbottle --bottle neolegacy --create --template win10_64`; native
d3dcompiler_43/47 + d3dx9_43 copied into its system32/syswow64 with
overrides. Launch: run-client.sh (= CrossOver wine wrapper with
`--bottle neolegacy --no-update --cx-app "Z:\...\Minecraft.Client.exe"`).
Verified live-window capture: 0% white, main menu visible with panorama +
selection bar. Mac process is named "Minecraft.Client.exe" now (grantable
in the computer-use allowlist; window capturable via
`screencapture -l <windowid>` — find id via Quartz CGWindowList).
- Drive input inside the bottle:
`"$CX/bin/wine" --bottle neolegacy --no-update --cx-app "Z:\Users\cole\neoLegacy-mac\tools\send_key.exe" <hexVK...>`
- Old launchers kept: run-client-wine8-legacy.sh (white-screen stack),
run-client-cx26.sh (raw wineloader attempt; fails on MoltenVK pathing).
Remaining fidelity items (visible in live capture): MINECRAFT logo missing
(ComponentLogo scene draws 1 placeholder quad; logo art likely in
Windows64Media/Media/Logo/ pngs or skin export — wire into bundle),
gray texture-substitution panel top-right, splash text, 9-slice panels.
Native no-Wine port plan: see task list / README (now feasible since Iggy is
replaced; needs platform shell + Vulkan 4J_Render impl via MoltenVK).
# Continuation brief (for future sessions — read this first)
Owner intent (Cole): run autonomously until goals are 100% done:
(1) game on mac via vulkan/moltenvk [DONE], (2) no SWFs — PNG + standard UI
library (RmlUi picked; NOT imgui) with behavior as if nothing changed,
(3) ogg-only audio [DONE — platform never used binka].
## Layout / commands
- Upstream clone: ~/neoLegacy (NEVER commit/push; origin=git.neolegacy.dev).
Two uncommitted working-tree patches (also in patches/): UIController.cpp
conflict-marker fix; CMakeLists.txt IGGY_LIBS guard.
- Our repo: ~/neoLegacy-mac → https://git.coah80.com/coah/neoLegacy-mac
(push works; token in macOS keychain; user coah).
- Toolchain: ~/.local/llvm22/LLVM-22.1.8-macOS-ARM64/bin (clang-cl, lld-link),
xwin SDK at ~/.cache/neolegacy-xwin/splat. brew is broken on this macOS beta.
- Build game: `cd ~/neoLegacy && PATH=$LLVM:$PATH cmake --build
build/windows64-clang-mac --config Release --target Minecraft.Client -j12`
(IGGY_LIBS=iggy_shim_w64.lib already cached; shim import lib lives at
Minecraft.Client/Windows64/Iggy/lib/iggy_shim_w64.lib).
- Build shim: `cd ~/neoLegacy-mac/iggy-shim && cmake --build build` then cp
build/iggy_shim_w64.dll into the game dir (see below). fetch-deps.sh builds
RmlUi 6.2 + FreeType (already built, /MT).
- Game dir: ~/neoLegacy/build/windows64-clang-mac/Minecraft.Client
- Run: `~/neoLegacy-mac/run-client.sh` (wine prefix ~/.local/share/neolegacy-wine,
DXVK+MoltenVK). Launch via lce-window MCP (launch/close/status tools).
- Drive input from INSIDE wine (mac perms can't target wine):
`WINEPREFIX=~/.local/share/neolegacy-wine wine ~/neoLegacy-mac/tools/send_key.exe 0D 28 71`
(hex VKs; 71=F2 = game screenshot → game dir screenshots/<date>.png; read PNG
to see screen). tools/list_windows.exe lists wine windows.
- Shim log: <gamedir>/iggy_shim.log (delete before each run).
- Regenerate assets: python3 gen-scenes-tsv.py && python3 gen-scene-bundles.py
(reads ~/neoLegacy-mac/ui-layout/*.json + ui-png/** + as3/**; writes
<gamedir>/uiassets/). uiassets/png is a symlink to ~/neoLegacy-mac/ui-png.
## UPDATE (session 2): FULL FLOW WORKS — boot to in-game
The invisible-UI problem is SOLVED and the entire critical path works:
title → main menu → Play → EULA → Load/Create/Join → Create New World →
world options → generate → **in-game with HUD**. Key changes since the
brief below:
- `raw_d3d.cpp`: raw D3D11 pipeline (device harvested from GDrawHandle first
member {ID3D11Texture2D*, SRV*, RTV*, w, h}; runtime D3DCompile; premult
blend; letterbox from bound-RT desc). GDraw draws were executing but
producing no pixels — this bypasses that. THIS is why UI now renders.
- `text_renderer.cpp`: glyphs uploaded as RGBA via textureUploadRGBA (not the
R8 GDRAW_TEXTURE_FORMAT_font path); em-unit metrics (advance*fontPx,
baseline from ascent, bitmap scaled fontPx/pixel_scale_correct); whitespace
advances w/o drawing; font-provider ranking (Mojangles_11 > _7 > Unicode).
- `scene_registry.cpp`: SetFocus(-1)=auto-focus first focusable (was matching
label nodes with default id=-1 — this unblocked every dialog/menu);
FJ_List controls (addNewItem/removeAllItems/HighlightItem/SetButtonLabel);
list-item press emits handlePress(listParentId, itemId).
- RmlUi restored to build (was temporarily stubbed via rml_stubs.cpp).
### Remaining polish (the "100%" tail)
1. Button/panel skin art: buttons are text-only; MainMenuButton selection bar
+ 9-slice dialog panels don't draw. In gen-scene-bundles.py the button art
resolves to a skin sprite but 9-slice scaling isn't applied; in ui_renderer
the panel BackgroundPanel sprite (DefineSprite_N/1.png) may be a small
9-slice source that needs stretching to the placement's child scale.
2. List-item font oversized: items inherit list node's bundle scale (e.g 4.9).
Fix: give list items a fixed fontPx independent of inherited scale, and lay
them out in the list's local pixel space.
3. RmlUi Rml::Initialise page-fault under wine (gated IGGY_SHIM_RML=1). Bisect
with logs inside rmlEnsureInit (SetRenderInterface→Initialise→LoadFontFace).
4. Then: sweep remaining scenes (inventory/containers/settings) for method
coverage; remove .swf/.arc from packaged build (uiassets/ is sole input).
## Original state brief (session 1)
- Game boots+runs on iggy-shim (Iggy DLL fully replaced). Scenes fingerprint,
bundles load, ticks paced (ReadyToTick gates while-loop — NEVER return
always-true), draws go through game's GDraw vtable (globals().gdraw).
- Input/focus/events work: Init(label,id)/SetLabel/SetFocus handled;
handlePress/handleFocusChange/handleInitFocus emitted (SaveMessage dialog OK
pressed successfully; intro auto-signals handleAnimationEnd at frame 90).
- PROBLEM A (visual): menu/dialog art does not visibly composite over the 3D
panorama. Draw calls ARE issued (log "draw <scene>: N quads"). Only the
active-layer scene gets IggyPlayerDraw from the game (e.g. ComponentLogo1080
draws 1 quad/frame at title). Suspects: (1) our RenderTileBegin call clears
depth+stencil and may draw into wrong RT state vs game's SetTileOrigin usage —
compare with how real Iggy sequences SetViewSizeAndWorldScale/RenderTileBegin/
RenderTileEnd per frame; maybe we must NOT call RenderTileBegin (game already
set tile origin) or must call RenderingBegin first; (2) projection y-flip:
set_projection_raw(x0,x1, y0=y0+th, y1=ty0) — verify quad coords land
on-screen (try DXVK_HUD or draw a fullscreen debug quad to test visibility);
(3) blend state color writes. NEXT STEP: draw one hardcoded 400x400 quad at
100,100 with no texture (tex0_mode=GDRAW_TEXTURE_none, color=red premult)
every scenePlayerDraw and check F2 screenshot; iterate from there.
- PROBLEM B: RmlUi backend (rml_backend/rml_render.cpp) is built+linked but
page-faults at Rml::Initialise under wine (wow64). Gated: IGGY_SHIM_RML=1 to
enable, default off. Debug via winedbg or add step logs inside rmlEnsureInit
(SetRenderInterface→Initialise→LoadFontFace) to bisect; suspect static-init
or TLS in rmlui.lib under /MT clang-cl; try compiling shim's rml files and
rmlui with /MTd? or disable RTTI mismatch (/GR-)? Check RmlUi requires C++14
exceptions ok. Alternative: link rmlui_core as source into shim CMake to rule
out lib-level issues.
- M-D remaining: per-scene fidelity for ~60 scenes (inventory slots via
custom-draw callbacks beginIggyCustomDraw4J, sliders, lists FJ_List with
AddItem etc.), then remove .swf/.arc from packaged build (uiassets/ is the
only shim input already).
## Key technical facts (hard-won; do not rediscover)
- iggy.h/gdraw.h in ~/neoLegacy/Minecraft.Client/Windows64/Iggy/include; game
compiles gdraw_d3d11.cpp itself; shim renders via GDrawFunctions vtable.
- Draw conventions: vformat v2tc2 {x,y,s,t}; quads: indices=nullptr,
num_vertices%4==0, num_indices=6*(n/4) uses builtin quad IB; rs.edge_matrix
MUST point at 4 floats (memcpy'd unconditionally); premultiplied alpha
(GDRAW_BLEND_alpha = ONE/INV_SRC_ALPHA); rs.use_world_space=1 → vertices in
display pixels; color[4] multiplies texture.
- Textures: MakeTextureBegin(owner,w,h,GDRAW_TEXTURE_FORMAT_rgba32,0,&info,&stats)
→ write info.texture_data (stride w*4) → MakeTextureMore → MakeTextureEnd.
Font glyphs: GDRAW_TEXTURE_FORMAT_font (R8) + tex0_mode=GDRAW_TEXTURE_alpha.
- Game contract: IggyPlayerCreateFromMemory(bytes,size,nullptr) → identify by
fingerprint (uiassets/scenes.tsv: name,size,crc32-first-4k,w,h,fps,docClass).
Properties (movie w/h) read BEFORE first tick. SetDisplaySize before
InitializeAndTickRS. SetUserdata(scene) after. Per frame:
while(ReadyToTick) TickRS; render: game calls gdraw_D3D11_SetTileOrigin(rtv,
dsv,null,x,y) then IggyPlayerDraw per scene then gdraw_D3D11_NoMoreGDrawThisFrame.
- UIControl_Base Init(labelUTF16,id) via CallMethodRS on control path;
UIScene externalCallback names: handlePress(controlId,childId F64),
handleFocusChange/handleInitFocus(id,child), handleCheckboxToggled(id,_,b),
handleSliderMove(id,_,v), handleAnimationEnd(), handleSelectionChanged(i),
handleRequestMoreData, handleTouchBoxRebuild.
- fourj AS3 framework (as3/<Scene>/scripts): FJ_Document/FJ_Base/FJ_Button/
FJ_Label/FJ_List; buttons have m_iId (game-assigned via Init), m_objNav*
strings (extracted into bundle V lines).
- Scene bundles: uiassets/scenes/<name>.scene: S w h fps; N depth zdepth frame
name png|- frames tx ty sx sy; V name up down left right. png dir w/o .png
suffix = sprite dir, frame files <n>.png (may skip numbers).
- Class-linked art: doc-class `public var Name:Class` (regex from as3) →
skin export (ui-layout/skin*.json exports) → skin png. `extract-ui-as3.sh`
decompiles 9,446 files from 370 canonical SWFs plus 3 distinct same-name
variants under `as3/_variants/`; 18 SWFs are timeline/art-only and contain
no ActionScript.
- Upstream quirks: skinHD.swf + platformskinHD.swf in Windows64Media/Media are
PE EXEs not SWFs (docs/UPSTREAM-ISSUES.md); 3 files have committed git
conflict markers.
- lce-window MCP screenshot tool lacks macOS screen-recording perms; use game
F2 (writes PNG) instead. osascript can set frontmost but cannot keystroke.
## Definition of done
1. Menus visibly render (PNG art + labels) and are navigable to: create world,
play, pause, options, inventory/containers — behavior parity.
2. RmlUi backend default-on (crash fixed) OR a documented decision that the
display-tree renderer + RmlUi-for-new-UI split is the final architecture.
3. Packaged build contains no .swf/.arc UI assets; game loads only uiassets/.
4. All committed+pushed to coah/neoLegacy-mac; journal_log updated.