Dome Keeper - PS Vita Port

# Dome Keeper - PS Vita Port Experimental PlayStation Vita port of **Dome Keeper**, adapted from the Godot PC release and tested with the custom **Godot 3.5 RC5 Vita** runtime. > **Current status:** technical preview under active development. The build boots on PS Vita hardware and reaches the in-game `LevelStage`. The three hard `LevelStage` blockers — a VRAM out-of-memory crash, texture WebP decode crashes, and map shaders exceeding the GPU's texture-unit limit — have now been addressed, and we are verifying that the map renders on hardware. Remaining work is gameplay rendering and performance. This is not a playable release yet. --- ## Release Status

Overall progress   Platform   State

The current Vita build has reached these steps on real hardware:

Step Progress
Boot — no C2-12828-1 crash ██████████████  Done
Title menu + background music ██████████████  Done
Controller input ██████████████  Done
New Game / Loadout flow ██████████████  Done
Enter LevelStage / Map ██████████████  Done
VRAM / OOM crash fixed ██████████████  Done
Texture decode — stale .stex ██████████████  Done
Map shaders within 8-sampler limit ██████████████  Done
Map renders on hardware █████████░░░░░  Testing
Playable gameplay loop █████░░░░░░░░░  Pending
Performance tuning ██░░░░░░░░░░░░  Pending
Overall ██████████░░░░  ~72%
What was fixed inside LevelStage (click to expand)
Three separate hard blockers inside `LevelStage` have now been addressed: 1. **VRAM out-of-memory** — the map's `ViewportLights` was allocating a full-size **3D + HDR** render target with post-processing mipmaps (>150 MB). Forced to 2D (`usage = 0`, `hdr = false`). 2. **`Failed decoding WebP`** — 136 stale `.stex` files held **old oversized image dimensions** (resized PNGs never re-imported, e.g. a flag at 2560×1536) that overflowed the Vita's WebP decoder. Regenerated from the current PNGs. 3. **Shaders over the texture-unit limit** — the PowerVR SGX543 exposes only **8 fragment texture units**, but `map_main_stones` (13 samplers) and `map_background_edges` (14 samplers) could not compile. Both reduced to ≤7 samplers. The next step is confirming the map actually renders on hardware.
--- ## Downloads For now, this repository publishes only the experimental VPK from the [Releases](../../releases) page. The final `game.pck` is **not included** and is still under development. You must own the original game. No commercial game assets are provided here. --- ## Installation 1. Download the latest VPK from the [Releases](../../releases) page. 2. Install the VPK on your PS Vita using VitaShell or [FMVita](https://github.com/WolffsRoom/FMVita). 3. A compatible `game.pck` will be required at the app folder once the data package is stable. Expected target path: ```text ux0:app/DOMEKEE01/game.pck ``` At this stage, the stable `game.pck` package is still being worked on. --- ## Controls | Button | Action | | :--- | :--- | | Left Stick / D-Pad | Move / Navigate | | Cross | Confirm / Interact | | Circle | Cancel / Back | | Triangle | Gadget / Context action | | Square | Secondary action | | L / R | Game actions, depending on state | | Start | Pause | Controls are still subject to change while the gameplay scene is being stabilized. --- ## Technical Progress The port has gone through several Vita-specific fixes. The most impactful, in order: - **`.stex` (StreamTexture) WebP format.** The correct layout is `GDST` header followed by `WEBP` then `RIFF` **directly**. A bad bulk "fix" had inserted an extra size field on one texture (`Load.png`), which the Vita GLES2 WebP decoder rejected (`Error unpacking WEBP image`). Reverting it to the standard layout fixed the title screen. The same standard layout works on both PC and the Vita fork. - **`SCREEN_TEXTURE` + 2D light = GPU freeze.** A `canvas_item` material that samples `SCREEN_TEXTURE` while drawn under a `Light2D` makes Godot compile the heavy LIGHT variant of the canvas shader, which **hangs the PowerVR SGX543 compiler** (hard freeze, not an error). `render_mode unshaded;` does **not** prevent this on the Vita fork. The fix is to remove the screen-texture dependency from non-essential overlays (shockwave distortion, vignette, screen-cover dissolve). - **Out-of-memory on `LevelStage`.** `Map.gd` sizes several Viewports to the **full map resolution** (`tilemap_size * TILE_SIZE`, ~3768x3768). `ViewportLights` additionally used the Godot defaults (`usage = USAGE_3D`, `hdr = true`), allocating a 16-bit float render target with mipmaps and a depth buffer — over 150 MB on its own. Forcing it to 2D RGBA8 removed the crash (`Cannot allocate mipmaps for 3D post processing effects`). - **Stage-transition freeze.** The `dissolveTransition` effect made a full-screen `ScreenCover` visible (compiling another lit canvas vertex variant that froze the GPU) and also did an expensive `get_viewport().get_texture().get_data()` framebuffer read-back. Both were disabled; the level now appears directly. - **Stale `.stex` → WebP decode crash.** Many source PNGs were resized by scripts but never re-imported, so the imported `.stex` files still held the **old oversized dimensions** (e.g. a flag stored at 2560x1536, a sprite sheet at 5175x316). Decoding those huge images overflowed the Vita's WebP decoder (`Failed decoding WebP image` after an out-of-memory). 136 stale textures were regenerated from the current PNGs. - **Map shaders exceeding the 8-sampler hardware limit.** The PowerVR SGX543 GPU exposes only 8 fragment texture units. `map_main_stones` (13 samplers) and `map_background_edges` (14 samplers) could not compile and hung the GLES2 compiler. Both were reduced to ≤7 samplers by dropping detail maps (damage/cracks, procedural cave noise, small-stone highlights) and reusing the noise map. Core look (tile shape, biome color, lit edges, falloff, gradient) is preserved. - **On-screen loading diagnostics.** `StageManager` was instrumented to load each scene dependency one at a time and show the current resource, item count, percentage and per-item timing on the Vita screen (and a `user://stage_load_trace.txt` log), which is how the blockers above were pinpointed. - Project resolution reduced to Vita-friendly dimensions (960x540) to reduce VRAM/CDRAM pressure. - Export filters updated so required data files (`.yaml`, `.json`, `.txt`, `.csv`) are included in the PCK. - Safety checks added around data loading to avoid infinite loops when files fail to open on Vita. - GodotSteam, PlayFab, and other PC-only integrations were removed or bypassed. - Shader syntax incompatibilities were corrected (PC-style constants such as `0f`, `0.5f`, `1f`; the `SCREEN_UV` / `SCREEN_TEXTURE` double-define workaround). More detail is available in [DetailsVitaPort.txt](DetailsVitaPort.txt). --- ## Tooling (`scripts/`) The [`scripts/`](scripts) folder holds the Python utilities written during the port. They operate on the local Vita build folder (absolute paths are embedded in each script — adjust them to your setup). See [`scripts/README.md`](scripts/README.md) for the full layout and safety notes. | Folder | Purpose | Key scripts | | :--- | :--- | :--- | | `stex/` | `.stex` (StreamTexture) WebP format inspection and repair | `revert_all_stex.py` (the official B→A fix), `scan_stex_format.py`, `check_stex.py`, `check_mip.py` | | `textures/` | Texture / atlas size reduction for the 4096 px and VRAM limits | `scan_textures_vita.py`, `optimize_vita.py`, `resize_stex_v2.py`, `restore_atlas_stex_v2.py` | | `shaders/` | Applies the `SCREEN_UV` → local-variable (`_suv`) workaround | `fix_shaders_vita.py` | | `validate/` | Pre-PCK checks of shaders, textures, refs and project settings | `validate_vitabuild.py`, `validate_refs.py` | | `restore/` | Restore resources from the original/reference PCK | `restore_all_from_original.py`, `restore_all_missing.py` | | `audio/` | WAV → IMA-ADPCM compression and audio bus patching | `compress_audio.py`, `patch_audio.py` | | `_history/` | Archived one-off patches and the original combined script blobs (reference only — not meant to be re-run) | — | > **Warning:** never run a `fix_all_stex`-style script. The harmful logic survives only inside `_history/combined_scripts_fb1d.py`; it re-inserts the broken WebP size prefix. Use `stex/revert_all_stex.py` to repair instead. --- ## Next Steps - **Confirm the map renders on hardware** now that textures decode and the map shaders fit the sampler limit (Dome, Keeper, tiles, HUD) and the stage is interactive. - Fix the sprite-sheet atlas alignment: several sheets were resized but their `AtlasTexture` pixel rects were not rescaled, so animations can be misaligned (loads without crashing, but looks wrong). - Cap the map Viewport render-target sizes (currently full-map resolution) to further reduce CDRAM and shorten the long shader/scene load time. - Investigate and recompress audio (IMA-ADPCM / 22050 Hz) to cut RAM usage. - Performance pass once the scene is stable, targeting a playable frame rate. --- ## Known Issues - Not playable yet — currently verifying that the gameplay scene renders on hardware. - Stable Vita-compatible `game.pck` is still in development. - Entering `LevelStage` still has a long load (the map's many custom shaders compile on the Vita's slow GLES2 compiler). - Resized sprite sheets can be visually misaligned until their atlas rects are rescaled. - Some visual effects (screen distortion, vignette, dissolve transition, tile damage/crack detail, fine background cave detail) are intentionally simplified or disabled on Vita to fit hardware limits. - Performance is not yet tuned. --- ## Main Tools Used ### GDRE Tools Used to inspect and extract Godot PCK data during research. [https://github.com/GDRETools/gdsdecomp](https://github.com/GDRETools/gdsdecomp) ### Godot PSVita Custom Godot 3.5 Vita runtime used for hardware testing. [https://github.com/SonicMastr/godot-vita](https://github.com/SonicMastr/godot-vita) ### PrincessLog / NetLoggingMgr PS Vita network logging tool used to capture hardware crash logs (the `princesslog-*.log` files that drive most of the debugging above). ### godotpcktool Used during PCK repacking experiments. [https://github.com/hhyyrylainen/GodotPckTool](https://github.com/hhyyrylainen/GodotPckTool) --- ## AI Notice This project used AI-assisted debugging and code review during the porting process. The work included crash-log analysis, Godot scene inspection, script compatibility fixes, and documentation of Vita-specific issues. --- ## Follow My Work [https://wolffsroom.wordpress.com/](https://wolffsroom.wordpress.com/)