TENCHU Z - NATIVE PC PORT: FEATURES
====================================

DISPLAY AND LAUNCHER (Alpha 0.1.4)
----------------------------------
  [ok]   F6 > Display: named graphics profiles, renderer, monitor, window mode,
         render scale and menu/overlay size. Profiles exclude frame timing.
  [ok]   Resizable launcher with scrolling, output presets including 1080p,
         and Safe launch without overwriting the saved setup.
  [exp]  Ultrawide gameplay projection with HUD proportions and group HUD
         size/position controls. Original framing for titles and movie playback.
  [ok]   Mouse sensitivity 0.01x - 100x in F6 > Camera and the launcher.
  [bug]  Vulkan mission-1 floor corruption remains unresolved; use D3D12.
  [ok]   Existing framerate controls and 60 fps patch are unchanged.
  [ok]   Release ZIP includes built-in shader presets, no user-installed mods.

Status:  [ok]     confirmed working in game
         [test]   built and boot-tested, needs confirming in a mission
         [exp]    experimental
         [bug]    known problem, being investigated
         [todo]   not done yet, parked for later
         [gone]   removed

Keep this file up to date when features are added or changed.


HOTKEYS (in game)
-----------------
  F6    Tenchu Z menu (all options below)
  F8    God mode on/off
  F5    Refill health
  F9    Pause / resume mouse look
  F10   Photo mode (free camera)
  F1    Save position (practice)
  F2    Load position (practice)


GAMEPLAY / CHEATS  (F6 > Cheats)
--------------------------------
  [ok]   God mode - the local player takes no damage. Enemies, co-op
         partners and scripted deaths (pits, mission-fail traps) unaffected.
  [ok]   Refill health, live health readout.
  [test] Free shop purchases.
  [test] Show / set money (ryo), capped at 99,999,999 like the game.
  [test] Damage you take: 0x - 3x (hard mode above 1x).
  [test] Damage enemies take: 0x - 5x.
  [test] One-hit kills.
  [test] Enemy readout: enemies alive, nearest enemy's HP and distance,
         HP of the last enemy you hit.


CAMERA  (F6 > Camera)
---------------------
  [ok]   Invert horizontal / vertical.
  [ok]   Horizontal / vertical camera speed.
  [ok]   Field of view (game default 48 degrees).
  [ok]   Camera distance (0.5x - 2.5x).
  [ok]   Photo mode / free camera (F10): left stick move, right stick
         look, RT/LT up/down, RB/LB fast/slow. The game keeps running.
         Fixed: left/down stick directions were dropped when combining
         controller slots. Stick diagnostics in the Camera tab.
  [ok]   Mouse look for keyboard & mouse players, mouse speed. The mouse
         is released while the F6 menu is open; F9 pauses it.


CONTROLLER  (F6 > Controller)
-----------------------------
  [test] Button remapping - any game button can be fed by any button or
         trigger. Saved as button_map in tenchuz.toml.
  [test] Left / right stick deadzones (game default 24% / 27%).
  [test] Rumble strength 0% (off) - 200%.
  [ok]   Fixed (2026-10-22): start-up could sit on a black screen for 20-40 s
         when some device stopped answering DirectInput. DirectInput is now
         off (Xbox, PlayStation and Switch controllers do not need it);
         F6 > Controller > Older USB controllers turns it back on
         (input_directinput, next start). SDK patch 7.
  [ok]   Keyboard & mouse keys (2026-10-22): every controller input can be
         bound to keys or mouse buttons in F6 > Controller. Set takes the
         next key or mouse button pressed (with Shift/Ctrl/Alt held, or a
         modifier on its own); + adds another key; Clear; Reset to
         defaults. Warns when a key is used twice or is an F-key hotkey.
         Applies at once, saved as keybind_* in tenchuz.toml.
  [ok]   Fixed: a key stopped working while Shift/Ctrl/Alt was held, and a
         modifier could not be bound on its own (SDK patch 5).


SPEEDRUN  (F6 > Speedrun)
-------------------------
  [test] Mission timer: runs from when your character appears after a
         mission loads until it leaves (loads excluded). The hub is not
         timed.
  [test] Run timer: in-game time (sum of missions) and real time.
  [test] Splits table, personal best per mission (speedrun_bests.txt),
         every attempt logged (speedrun_log.txt). Deaths never count as
         bests.
  [ok]   Practice: save / load position (F1 / F2), within one area. Uses
         the game's own placement routine (sub_82342500) and also moves
         the other copies of the position the game keeps (physics, etc.).


ON-SCREEN PANEL  (F6 > HUD)
---------------------------
  [ok]   Hide the game's HUD (2026-10-22): F11 or F6 > HUD, saved as
         hide_game_hud. In a mission the GPU plugin skips every draw after
         the game's final screen pass (822F99ECDB1B0ACD) until the frame is
         shown, so subtitles, banners and the pause menu are hidden too while
         it is on; title and hub menus are unaffected. SDK patch 8. (Skipping
         the HUD's own task, CCockpit sub_82394AF0, only froze it: the
         sprites are drawn elsewhere.)
  [ok]   Frame rate (relabelled 2026-10-22): "FPS" is the game's real
         frame rate (30, as on the Xbox 360; 60 with the 60 fps option).
         "Window redraws" is how often the window is repainted (follows
         the monitor and repeats the same game frame), so a 144 Hz monitor
         does not mean the game is failing to reach 144.
  [test] Health, enemies (alive / nearest / last hit), speedrun timer,
         position.
  [ok]   Any corner of the screen.


VIDEO  (F6 > Shader, launcher)
------------------------------
  [ok]   Render scale 1x - 7x (the game always draws 1280x720; scale is
         the real internal resolution, e.g. 3x = 3840x2160).
  [test] Renderer (2026-10-22): Direct3D 12 (default) or Vulkan (work in
         progress), in the launcher or F6 > Game > Renderer (restart to
         switch); gpu_backend in tenchuz.toml. If Vulkan cannot start (no driver, old GPU) the
         game falls back to Direct3D 12 and says so in F6 > Game. Vulkan
         follows "Allow tearing" (no tearing by default). Shader presets
         need Direct3D 12. Checked on NVIDIA (menus and mission 51); other
         GPUs untested.
  [test] Fixed: with Vulkan, characters were noisy pixels on NVIDIA (the
         alpha test ignored use_fuzzy_alpha_epsilon), and roofs, wooden
         beams, carts and trees were missing or see-through (textures with
         a LOD bias were scaled to near black). SDK patch 6. Checked in
         mission 51 against Direct3D 12.
  [test] Black menu fix (2026-10-23): F6 > Game > "Sync GPU-written memory
         every frame" (clear_memory_page_state in tenchuz.toml, applies at
         once). On by default; off is Xenia's
         d3d12_clear_memory_page_state = false, which a player reports
         fixes menus showing black. Not yet tried on a PC with black menus.
  [test] Performance settings (2026-10-23): readback_memexport = false and
         occlusion_query_enable = false in the shipped tenchuz.toml, the
         choices Xenia players use for this game (no CPU wait on GPU memory
         writes; visibility queries answered "visible" instead of measured).
         A/B in a mission (RTX 4060 Ti, Direct3D 12): no visible difference
         either way, nothing broke, so they stay for slower PCs. Vulkan ran
         at about the same frame rate with them. Set either back to true if
         something looks wrong.
  [exp]  60 fps (2026-10-22): F6 > Game > 60 fps (experimental), or the
         launcher's "60 fps while playing"; frame_rate_60 in tenchuz.toml,
         applies at once. The game normally shows a new frame every second
         vertical blank (30 fps); while your character is in the world it
         now shows one every blank. Menus stay at 30 (they ran too fast at
         60). Game speed stays normal because the clock is still the 60 Hz
         refresh. Measured 55-60 fps in missions on Direct3D 12, about 54 on
         Vulkan. Not yet checked: cutscenes, the pause menu.
  [bug]  Vulkan, NVIDIA (2026-10-22): the wooden walkway under the eaves
         in mission 1 is speckled red/green or flat purple (floor shader
         ACFA07437578EA9C). Direct3D 12, the default, draws it correctly.
         All its inputs (textures, vertex data, constants, texture slots)
         were checked and are correct; the wrong result changes when
         unrelated code is added to the shader, so it looks like undefined
         behaviour in the NVIDIA Vulkan shader compiler. Direct3D 12's
         bindful mode showed the same purple. Parked.
  [test] Vulkan: the Xbox 360 rule "0 or a denormal times anything is 0"
         now also treats denormals as zero on GPUs that keep them (NVIDIA
         on Vulkan cannot flush them). SDK patch 9. Did not fix the floor.
  [test] Background speed (2026-10-22): the game runs at above-normal
         priority so it keeps its frame rate in missions while its window
         is in the background (Windows boosts only the window in front).
  [gone] F6 > Video tab removed (2026-10-21): its live overrides of the
         game's own post-processing (exposure, bloom, HDR, blur, tone
         mapping, depth of field) are replaced by the shader presets. The
         frame size readout went with it; render scale is in the launcher.
         Old fx_* keys were removed from tenchuz.toml.
  [ok]   ReShade works (Direct3D 12; colour effects only, see docs).
  [ok]   Custom pixel shaders: put <HASH>.ps.hlsl in shader_overrides\ or
         mods\<Mod>\shaders\ and it replaces that game shader (compiled at
         startup; errors fall back to the original). shader_overrides\
         wins over mods. Off switch: shader_overrides_enabled in
         tenchuz.toml. Guide: docs\shader_modding.md.
  [ok]   Shader presets: each subfolder of shader_overrides\ (or a mod's
         shaders\) is a preset. F6 > Shader > Preset picks one, or Original;
         switching needs a restart (Restart now button). Saved as
         shader_preset in tenchuz.toml.
  [ok]   "Modern Look" preset (extras\shader_overrides\Modern Look):
         replaces the final screen pass (822F99ECDB1B0ACD) and adds
         sharpening, clarity, bloom, a highlight roll-off, colour grading,
         vignette and dithering on top of the game's own blur/DOF/bloom.
  [ok]   "Manga" preset (extras\shader_overrides\Manga): ink outlines,
         flat tone bands, halftone screentone and paper colour; the Colour
         slider turns it into a colour comic.
  [ok]   Manga ink lines drawn on the dark side of edges only (half as
         thick) and sized in whole screen pixels (no pixelation when thin).
  [ok]   F6 > Shader: live sliders for the active preset (from its
         preset.ini), an effects on/off switch and a split-screen compare.
         Values saved per preset in shader_settings.ini. Shader files read
         them as XeUser(0..47).
  [ok]   The game passes the camera (eye, direction, field of view) and a
         clock to every shader (XeUser(48..61)), so shaders can rebuild
         world positions. Verified with a world grid on the hub puddle.
  [gone] Modern Look puddle water (79481E88F9E67594) removed 2026-10-22: it
         only affected puddles, so puddles are back to the game's own
         shader and its 7 sliders are gone. The depth effect sliders moved
         from XeUser(22..30) to XeUser(15..23).
  [ok]   Modern Look depth effects: ambient occlusion, atmospheric haze
         with tint, depth of field focused on the player, and light shafts
         from bright distant areas (they always come from above the screen;
         the moon's real position is not known). 9 sliders. The game's depth
         texture holds about k / distance; k is measured every frame at the
         player (the game passes the player's screen position and distance,
         XeUser(40..43)). Fixed 2026-10-21: haze only reached ~10 ft and
         DOF/shafts did nothing, because depth was read as plain distance.
  [todo] Water effects (rivers and puddles): left as the game draws
         them. River water's shader is not identified yet (probably drawn
         additively); an in-game shader picker would be the next step.
  [ok]   Fixed: with shader overrides active, some textures came out as a
         flat colour (mission 1: purple wooden walkway, magenta HUD orb).
         Cause: overrides switched the renderer to its bindful resource
         mode. They now work in the default bindless mode, so the renderer
         is left alone.


ONLINE  (F6 > Online, game's System Link mode)
----------------------------------------------
  [ok]   System Link multiplayer over IP: host and join with the game's own
         System Link menu. Verified with two copies on one PC (both players
         in the village). Not yet tested between two PCs or over the
         internet. Guide: docs\multiplayer.md.
  [test] Join by IP (net_join_ip, set by Join in F6 > Online): search asks
         that host directly, so play works over virtual LANs (ZeroTier,
         Radmin, Tailscale) or port forwarding. The join box takes codes or
         plain addresses.
  [test] F6 > Online > Advanced: This PC's address (net_bind_ip) for
         virtual LANs, this PC's local addresses with Copy buttons, and the
         router (UPnP) on/off switch.
  [ok]   Join codes, the simple way (2026-10-21): F6 > Online > Host a game
         > "Get my join code" opens the game's ports on the router (UPnP,
         remembered as net_upnp; again at every start, closed at exit) and
         shows the code (e.g. K3F9-2QX7) with a Copy button. Friends paste it
         under Join a friend (Paste button or Ctrl+V) and press Join, then
         Search in System Link. Verified with two copies on one PC (code
         copied and pasted, search found the host, join worked). Not yet
         tested between two networks.
  [ok]   Router port opening verified with a real router (opened, internet
         address read, closed again on exit).
  [test] If the router refuses, the internet address comes from a public
         STUN server (Google, else Cloudflare) and the code is still shown,
         with a note to forward the ports by hand or use a virtual LAN.
  [test] With a virtual LAN address set (Advanced > This PC's address), the
         join code stands for that address. The two-copy test script uses this
         (each copy shows a code for 127.0.0.x).
  [test] Each PC tells the other players its internet address
         (net_public_ip, in its System Link address), so players on other
         networks reach it across the internet.
  [ok]   Fixed: the host answered System Link searches only with a
         broadcast, so players joining by code never saw the game. It now
         also answers searchers from other networks directly.
  [ok]   Fixed: a host with a join address left from an earlier game sent
         its search answers there (or to itself) instead of to the player
         searching. Hosts now always answer the searcher.
  [test] Recent table in F6 > Online: the last 5 codes joined, with date,
         and Join / Copy / Remove buttons (net_recent_hosts).
  [test] Fixed: Ctrl+V / Ctrl+C / Ctrl+A did nothing in menu text fields
         (the runtime never passed Ctrl to the menus correctly).
  [ok]   Player name (F6 > Online > Your name, user_name): what other
         players see instead of "User". Applies after a restart (Restart
         now button). Verified with two copies (Rikimaru and Ayame shown in
         the joined game). Fixed 2026-10-21: any other name crashed the game,
         because the runtime kept profile files in a folder named after the
         player, and a new name meant an empty folder. It now always uses
         the "User" profile folder, so saves and settings stay put.
  [ok]   Fixed 2026-10-22: the partner card at the top left (colored P1-P4
         badge frame, health bar, name) showed as striped boxes. Cause: a
         recompiler bug in the vector pack instructions vpkuwus / vpkuhus
         when the result register is also an input (vpkuwus v0,v0,v0): the
         game builds the card's sprite sizes that way at startup, and they
         came out as 65535. Fixed in the recompiler (SDK patch 4); every
         place the game uses these instructions was regenerated. Verified
         in a co-op mission: the card matches the Xbox.
         (The flashing light specks in the air are dust; the Xbox has them
         too.)
  [ok]   tools\systemlink_test.ps1 runs two copies on one PC for testing
         (join with the codes; -PresetJoin skips them). Runs both at 1x
         render scale by default: at 3x the two copies fight over the GPU,
         the one you are not playing in drops to a few frames a second and
         enemies stutter on the other screen (verified: smooth at 1x).
  [test] The game keeps full speed when its window is in the background
         (1 ms timer, Windows background throttling off), so a host who
         alt-tabs does not slow down the game for the other players.
  [ok]   Single-player levels in multiplayer (2026-10-23): F6 > Online,
         pick one of the 14 single-player missions and tick "Use this level
         in multiplayer" in the System Link lobby (host). A background search
         finds the lobby's level setting (layout and level ids from a
         community Xenia cheat table) and keeps the chosen level written
         there. Verified hosting System Link: Daylight Battle On Deck, then
         Divine Punishment Tenchu, loaded as chosen.

GAME  (F6 > Game)
-----------------
  [ok]   Skip intro movies (logos and opening); story cutscenes still play.
  [test] Mute when the window is not focused (on by default).
  [test] Exit game (button at the bottom of the F6 menu, with confirm).


MODS
----
  [ok]   mods\ folder next to tenchuz.exe: each mod mirrors the game folder
         (mods\MyMod\DATA\...). Replaces and adds files without touching the
         game files. Folders starting with _ are disabled. Later in the
         alphabet wins.
  [test] Launcher mod manager: enable/disable checkboxes and load order
         (Up/Down). Applied by renaming folders when you save or launch.
  [ok]   Loaded mods listed in F6 > Mods.
  [ok]   Mods can ship shaders in mods\<Mod>\shaders\ (see VIDEO).


LAUNCHER  (tools\launcher\Tenchu Z Launcher.cmd)
------------------------------------------------
  [ok]   Render scale, window size / fullscreen, frame rate + vsync.
  [test] "Game speed and frame rate" (2026-10-22): the refresh setting is
         labelled "Console refresh (Hz)" with a note that it is the game's
         clock (60 Hz = normal speed, 30 fps), so nobody expects 144 Hz to
         give 144 fps. Checkbox for the 60 fps option.
  [ok]   God mode, free shopping, skip intros, mouse look, mods on/off.
  [ok]   Dump shaders for shader modding (writes shader_dump\ with an
         override stub and interface file for every pixel shader).
  [test] Mod manager (see above).
  [ok]   Works next to tenchuz.exe (packaged) or in the build tree.
  [ok]   Asks before closing a running game; shows errors in a dialog.


RELEASE  (tools\package_release.ps1)
------------------------------------
  [ok]   Version (now 0.1.3-alpha): the window title reads "Tenchu Z - HoloCatt
         Recomp Project - v<version>"; the F6 menu shows the version too
         (tenchuz-recomp/src/version.h).
  [ok]   Setup checks the game version (SHA-1 of default.xex: Tenchu Z USA/
         Europe) before extracting, and rejects files that aren't Xbox 360
         disc images.
  [ok]   Keyboard and mouse on by default in the release settings
         (mnk_mode), so the keyboard works however the game is started.
  [ok]   Start hint: "Press F6 for the Tenchu Z menu" at the top of the
         screen for 30 seconds after start, or until F6 is first pressed.
  [ok]   F6 > Tools (memory scanner, camera probe) hidden unless
         developer_tools = true in tenchuz.toml.
  [ok]   Public source and releases: github.com/Llamapixels/TenchuZRecomp
         (MIT license; no game files or generated code).
  [ok]   Release zip: release\TenchuZ-PC-<date>.zip (about 15 MB). Holds the
         port, the Visual C++ runtime, setup and launcher, a clean
         tenchuz.toml, the shader presets, docs and licenses. No game files;
         the packaging script refuses to include any.
  [ok]   "Setup Tenchu Z.cmd" (tools
elease\setup.ps1): extracts the
         player's own Tenchu Z .iso into extracted\ (no extra programs) and
         creates the profile settings the game needs. Verified: unzipped
         release + ISO -> identical game files, game starts with the Modern
         Look preset.
  [ok]   README.txt in the release: setup, playing, hotkeys, online.

DEVELOPER TOOLS  (F6 > Tools, only with developer_tools = true)
-----------------------------------------------------------------
  [ok]   Camera probe: finds camera data by turning the camera and diffing
         memory; writes camera_probe_<date>_<time>.txt.
  [ok]   Memory scanner with watch list and pinning.
  [ok]   Crash handler logs guest registers and call stacks.


SETTINGS
--------
  All settings live in tenchuz.toml next to tenchuz.exe. The launcher and
  the F6 menu both edit it in place (comments and [log.levels] kept).
  Do not use the runtime's own F4 settings screen "Save to config" button:
  it rewrites the whole file and drops those.


PLANNED / NOT YET DONE
----------------------
  - First-person camera mode.
  - Texture converter for .xpr (modding tools) - separate task.
  - Unlock everything / save editor.
