GitHub Vita Lite - Wolff's Store
Code / README | Releases | Issues
WolffsRoom/godot4-psvita

README.md

35119 bytes · Original / download

Godot 4 for PlayStation Vita

A custom Godot 4.8-dev7 runtime with native GXM rendering, plus a Windows editor that exports PS Vita VPKs directly.
This is not an official Godot release.

RELEASEV0.3 GODOT4.8-DEV7 DOWNLOADS272 2DNATIVE GXM 3DEXPERIMENTAL


If you enjoy my work, consider supporting the development!

[image: Buy Me A Coffee]

Overview and Features - [What This Project Is](#what-this-project-is) - [Windows Editor with PS Vita Export](#windows-editor-with-ps-vita-export) - [LiveArea Template Selection with Previews](#livearea-template-selection-with-previews) - [PS Vita Trophies (In Development)](#ps-vita-trophies-in-development)
Engine and Architecture - [Runtime Architecture](#runtime-architecture) - [Native GXM 2D Renderer](#native-gxm-2d-renderer) - [Experimental GXM 3D Renderer](#experimental-gxm-3d-renderer) - [Audio, Input, Memory and Data Loading](#audio-input-memory-and-data-loading)
Getting Started - [Games Running on This Engine](#games-running-on-this-engine) - [Download and Quick Start](#download-and-quick-start) - [Limitations](#limitations)
Development and Resources - [Building from Source](#building-from-source) - [Repository Structure](#repository-structure) - [Contributors](#contributors) - [Credits](#credits)

What this project is

Godot 4 does not run on the PS Vita out of the box: the Vita has a 444 MHz quad-core ARM Cortex-A9, an SGX543 GPU driven through Sony's GXM API, 512 MB of RAM and no Vulkan or desktop OpenGL. This port has three parts:

Part What it does
Runtime (platform/vita) Godot 4.8-dev7 compiled for ARM as a position-independent libgodot.so, with a Vita OS layer, native GXM 2D/3D renderers, audio, input and file access.
Loader (platform/vita/loader) A small Vita eboot.bin that maps, relocates and starts libgodot.so, resolves its imports against the Vita SDK, shows the loading animation and manages CapUnlocker, logs and data paths.
Windows editor (modules/vita_editor + platform/vita/editor) A Godot 4.8-dev7 Windows editor build in which PS Vita is a built-in export platform. It turns any compatible project into an installable VPK, with LiveArea, trophies and a separate data folder.

Windows editor with PS Vita export

The release ships Godot4Vita.exe, a portable Windows editor. PS Vita appears in Project > Export > Add… for every project, without installing an addon, Python, WSL or VitaSDK.

PS Vita export preset in the Godot editor

How the export platform was integrated

Export options

Option Effect
Data > Separate Folder (default on) The VPK contains the runtime and LiveArea; the game data goes into a folder next to it, which you copy to ux0:data/<Folder Name>/. Re-installing a large game no longer requires rebuilding a huge VPK. Turn it off to put everything inside the VPK. Earlier exports are kept with a .previous-… suffix.
Performance > CapUnlocker disabled, optional (uses the fourth CPU core when the CapUnlocker plugin is installed) or required (shows instructions and exits when missing). When available, the audio mixer can run on the reserved core.
Textures > GPU Format RGBA4444 (default, half the GPU memory and transfer size) or RGBA8888 (full precision for gradients and soft alpha). The conversion happens when the loader uploads each texture; project files are not changed.
LiveArea > Style The template.xml layout, with visual previews (see below).
Application Title, Title ID and version written to PARAM.SFO.
Custom Template / Assets Optional custom runtime template and 8-bit indexed PNG images: icon 128 × 128, background 840 × 500 and startup button 280 × 158. Empty fields use the bundled Godot Vita images.

PS Vita export options

Projects opened in the editor

The same editor opens and exports the ported games. These projects were adapted for the Vita runtime (960 × 544 viewport, Compatibility renderer, PS Vita preset) and open normally on the PC:

Dodge the Creeps open in Godot4Vita
Dodge the Creeps (2D, the engine's first test game)

Tenebrarium open in Godot4Vita
Tenebrarium (2D, native GXM canvas with NinePatch and polygons)

Overburden open in Godot4Vita
OVERBURDEN (first 3D port, experimental GXM 3D)

Example export

examples/vita_export contains a minimal project, the Exemplo.vpk exported from it and its ux0:data/exemplovita data folder. Use it as a reference for the expected VPK and data layout, or install it to check that a Vita is ready for this runtime.


LiveArea template selection with previews

The LiveArea is the Vita home screen page of a game. Its layout is defined by sce_sys/livearea/contents/template.xml. The export preset exposes the LiveArea > Style list (a1–a5 for games, plus the other system layouts for reference) and Show template previews, a horizontally scrolling strip with a picture of each layout, so the right template.xml can be chosen without guessing.

LiveArea template previews in the export dialog


Default game loading screen

Every game exported with this engine opens with the same native loading animation. After the LiveArea pic0, the Vita loader shows this 960 × 544 animation while libgodot.so is being loaded and relocated, before the engine itself exists. It replaces the black screen that used to last several seconds.

Godot 4 Vita loading animation

How it works:


PS Vita trophies - in development

A PS Vita Trophies tab is added to the editor's bottom panel. It builds a real trophy package for the VPK.

Trophy set configuration Trophy list editor

  1. Set: enables trophies in the VPK and sets the title, description and Communication ID (defaults to the Title ID + _00).
  2. Import Steam: imports a game's achievements from the Steam Web API (GetSchemaForGame/v2) with a user key, or from a saved JSON response. Names, descriptions, hidden flags and icons are imported; re-importing keeps existing IDs and edits. The key is only kept for the session.
  3. Trophies: edit each trophy's key, name, description, grade (Bronze/Silver/Gold/Platinum), visibility and icon, or add trophies manually.

Generate base files + TRP writes vita_trophies/ in the project (TROPCONF.SFM, TROP.SFM, 8-bit PNG icons at 320 × 176 and 240 × 240, an achievement-to-trophy map) and a TRP v2 container (64-byte big-endian entries, 16-byte aligned data, SHA-1). The exporter regenerates the TRP and places it at sce_sys/trophy/<COMMUNICATION_ID>/TROPHY.TRP in both data modes. Packages are unsigned and intended for NoTrpDrm.

[!NOTE] Status: the editor panel, Steam schema import, PNG-8 conversion, TRP generation and VPK packaging are implemented and tested on Windows. The runtime unlock bridge (sceNpTrophy) is not implemented yet, so games cannot unlock trophies in this release.


Runtime architecture

eboot.bin (loader, C)                      libgodot.so (Godot 4.8-dev7, C++)
├─ boot animation (2 decoder threads)      ├─ OS_Vita / DisplayServerVita
├─ ELF loader + relocations (so_util)      ├─ RasterizerGXMVita (2D canvas, 3D scene)
├─ default_dynlib: SDK import table        ├─ AudioDriverVita (SceAudio)
├─ GXM bridge (vita2d + GXM programs)  ◄───┤ JoypadVita + front touch
├─ CapUnlocker probe / logs                └─ godot_vita.cpp entry: data folder + game.pck
└─ game_data/  or  ux0:data/<folder>/

Native GXM 2D renderer

Godot's Compatibility renderer relies on GLES3 shaders that the Vita's shader compiler cannot handle reliably. Instead, rasterizer_gxm_vita.cpp + gxm_canvas_vita.inc translate Godot CanvasItem commands directly into GXM draws through a pinned libvita2d context. No GLES shaders are used for 2D.

Implemented and validated in real games:

Validated on hardware with Dodge the Creeps, Ambidextro, Deltarune Lightners Live Plus and Tenebrarium.


Experimental GXM 3D renderer

rasterizer_scene_gxm_vita.inc (built into libgodot_gxm3d.so, enabled at run time by gxm3d.cfg) draws Godot MeshInstance3D scenes with GXM, sharing the 2D canvas for UI. It is used by the Overburden port and by the Buckshot Roulette validation.

Not available yet: real-time shadow maps, fog, screen-space effects, custom spatial shaders and post-processing.


Audio, input, memory and data loading


Games running on this engine

The clips below were recorded directly from the local Godot project builds. They show the projects running on the desktop editor/runtime, not Vita emulation; hardware status is described under each game.

View games and gameplay previews

Animated Godot4Vita game showcase

Dodge the Creeps

Dodge the Creeps repository on GitHub

Dodge the Creeps running on Godot4Vita

**2D - Godot's official demo.** The first game on the engine. Gameplay, collisions, HUD, audio and controls are confirmed on a physical Vita.

Ambidextro

Ambidextro repository on GitHub

Ambidextro running on Godot4Vita

**2D commercial game.** Beta release; playable on hardware with the native GXM 2D renderer.

Deltarune Lightners Live Plus

Deltarune Lightners Live Plus repository on GitHub

Deltarune Lightners Live Plus running on Godot4Vita

**2D fan game.** Playable on hardware; v1.0 is available and runs at 60 FPS.

Tenebrarium

Tenebrarium repository on GitHub

Tenebrarium running on Godot4Vita

**2D.** Alpha running on hardware. The port drove NinePatch, polygon, SubViewport, batching and touch support in the native renderer.

OVERBURDEN

OVERBURDEN repository on GitHub

OVERBURDEN running on Godot4Vita

**First 3D game.** The full game is playable on hardware at approximately 30 FPS with the experimental GXM 3D renderer.

Buckshot Roulette

Buckshot Roulette running on Godot4Vita

**3D validation project.** It boots and its main menu and options work. Gameplay does not start yet because of the complexity of its 3D scene.

Lantern Crossing

Lantern Crossing repository on GitHub

Lantern Crossing running on Godot4Vita

**3D.** A PS Vita port by [jeeve-javari](https://github.com/jeeve-javari), using the experimental GXM 3D renderer and Vita-specific scene adaptations.

Download and quick start

  1. Download Godot4Vita-v0.2-Windows-x64.zip from the latest release and extract the whole folder. Keep vita/ next to Godot4Vita.exe.
  2. Open or create a project. In Project > Export > Add… choose PS Vita and click Prepare settings for PS Vita.
  3. Set the title, a unique 9-character Title ID and the version, choose the LiveArea style and the data folder name.
  4. Click Export Project and save the .vpk.
  5. On the Vita (HENkaku/Ensō with kubridge installed), install the VPK with VitaShell and copy the generated data folder to ux0:data/.

The PS Vita export and trophy panels are currently labelled in Portuguese (for example Preparar configurações para PS Vita, Mostrar prévias dos modelos, Troféus PS Vita). The Exemplo/ project in the release is a ready-to-export example. Detailed Portuguese guides are included: LEIA-ME.md, TROFEUS.md, RGBA4444.md.


Limitations


Building from source

Requirements: Linux/WSL, VitaSDK, Python 3, SCons, CMake, the patched VitaGL build described in platform/vita/vitagl, and MinGW-w64 (POSIX threads) for the Windows editor.

Runtime, loader and export template (WSL):

export VITASDK=/usr/local/vitasdk
platform/vita/tools/build_release_template.sh /path/to/vitagl /path/to/output
# -> libgodot.so, loader/godot_loader.vpk, vita_release.zip

Windows editor (WSL with MinGW), then assemble the portable folder (Windows Python):

platform/vita/tools/build_windows_editor.sh
python platform/vita/tools/package_windows_editor.py
python platform/vita/tools/archive_windows_editor.py

See BUILDING.md, INTEGRATED_WINDOWS.md and GXM_BACKEND.md.


Repository structure

Path Purpose
platform/vita/ Vita OS, display, input, audio and file access
platform/vita/rasterizer_gxm_vita.cpp, gxm_canvas_vita.inc Native GXM 2D renderer
platform/vita/rasterizer_scene_gxm_vita.inc, godot_vita_gxm3d.cpp Experimental GXM 3D renderer and its entry point
platform/vita/loader/ Loader, ELF relocation, SDK import table, GXM bridge, boot animation
platform/vita/editor/addons/psvita/ Export platform, LiveArea previews, trophy tools (GDScript)
modules/vita_editor/ Native editor plugin that registers PS Vita in the Windows editor
platform/vita/tools/ Build, packaging, template, validation and coredump tools
platform/vita/tests/ ColorRect, canvas, 3D mesh and Dodge the Creeps test projects

Contributors
People who have contributed code and project improvements to Godot4Vita.

[image: Godot4Vita contributors]
View all contributors


Credits

Godot engine code and port additions are provided under the MIT license; third-party components retain their respective licenses.