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

13 KiB

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/.png; read PNG to see screen). tools/list_windows.exe lists wine windows.
  • Shim log: /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 /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 : 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//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/.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 .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.