Vita Texture Cache Builder
Builds validated RGBA4444 and BC3 texture caches for DeltaruneVita.
---
# DeltaCache
**DeltaCache** prepares external texture caches for **DeltaruneVita** from a final, shipped `data.win`.
It generates both:
```text
RGBA4444 → page_NNN.r444
BC3/DXT5 → page_NNN.bc3.pvr
```
for every internal Texture Page, then validates the result against the same TXTR metadata the Vita Runner uses.
> DeltaCache does not include or distribute Deltarune game files. You must provide your own `data.win`.
## Why DeltaCache exists
DeltaruneVita can use different texture representations depending on the selected runtime mode.
Instead of converting textures on the Vita, DeltaCache prepares both representations offline:
```text
final data.win
↓
parse TXTR
↓
export Texture Pages
↓
build R444 + BC3
↓
validate against TXTR
↓
prepared package
```
The generated cache is tied to the exact `data.win` it was built from through:
```text
sourceSize
sourceOffset
width
height
```
This prevents stale cache files from being silently reused with a different Texture Page layout. The current tool reads these values directly from the final TXTR chunk. fileciteturn40file1L30-L45
---
## Features
- Builds `.r444` caches for every internal Texture Page
- Builds `.bc3.pvr` caches for every internal Texture Page
- Parses `FORM -> TXTR` directly from the final `data.win`
- Uses real TXTR `blobOffset`, `blobSize`, `width` and `height`
- Generates Runner-compatible 20-byte R444 headers
- Handles Chapter 3's separate VTC5/VTC6 cache version
- Generates and validates `complete.vtc`
- Validates PVR v3 / BC3 / sRGB metadata
- Performs a physical re-validation pass before marking a chapter complete
- Detects missing or extra cache files
- Supports external TXTR pages safely
- Produces per-chapter manifests
- Keeps the original input files untouched
- Supports automatic migration from nearby previous DeltaCache versions
---
## Project structure
```text
DeltaCache/
├─ assets/
├─ chapters/
├─ prepared/
├─ source/
├─ CHANGELOG_v0_3_6.md
├─ prepare_texture_cache_v0_3_6.bat
├─ README.md
└─ RUNTIME_SELECTION.md
```
### `assets/`
Repository branding and documentation assets.
Suggested files:
```text
assets/
├─ icon.png
├─ logo_black.png
└─ logo_white.png
```
### `chapters/`
Place the final `data.win` files here.
```text
chapters/
├─ 1/
│ └─ data.win
├─ 2/
│ └─ data.win
├─ 3/
│ └─ data.win
├─ 4/
│ └─ data.win
└─ 5/
└─ data.win
```
The input must be the **final/shipped** `data.win` that will actually be used on the Vita. fileciteturn40file1L5-L13
### `prepared/`
Generated output is written here.
Do not commit generated game data to Git.
### `source/`
Contains the helper scripts and required tooling.
---
## Usage
Run:
```text
prepare_texture_cache_v0_3_6.bat
```
DeltaCache scans the available chapters, parses each TXTR and prepares both texture formats.
Typical output:
```text
prepared/
├─ chapter1/
│ ├─ data.win
│ ├─ texture_manifest.json
│ ├─ texture-cache/
│ │ ├─ page_000.r444
│ │ ├─ page_001.r444
│ │ ├─ ...
│ │ └─ complete.vtc
│ └─ pvr/
│ ├─ page_000.bc3.pvr
│ ├─ page_001.bc3.pvr
│ └─ ...
├─ chapter2/
├─ chapter3/
├─ chapter4/
├─ chapter5/
└─ prepared_manifest.json
```
This matches the current prepared layout documented by the tool. fileciteturn40file1L15-L27
---
## R444 format
Each `.r444` file contains:
```text
20-byte header
+
width * height * 2 bytes of raw RGBA4444
```
Header:
```text
uint32 magic
uint32 sourceSize
uint32 sourceOffset
uint32 width
uint32 height
```
All fields are little-endian.
The source fingerprint fields come directly from the final TXTR:
```text
sourceSize = blobSize
sourceOffset = blobOffset
width = TXTR width
height = TXTR height
```
Pixels are stored raw, without zlib compression. fileciteturn40file1L30-L45
### Alpha packing
```text
A4 = 0 if A == 0
A4 = min(15, (A + 15) >> 4) otherwise
```
### Cache magic
```text
Chapter 1 → VTC1
Chapter 2 → VTC1
Chapter 3 → VTC5
Chapter 4 → VTC1
Chapter 5 → VTC1
```
Chapter 3 intentionally uses a separate cache version. fileciteturn40file1L48-L59
---
## `complete.vtc`
After every required page has been generated and physically revalidated, DeltaCache writes:
```text
texture-cache/complete.vtc
```
Format:
```text
uint32 completeMagic
uint32 txtr.count
```
Magic:
```text
Chapter 1 → VTC2
Chapter 2 → VTC2
Chapter 3 → VTC6
Chapter 4 → VTC2
Chapter 5 → VTC2
```
Before creating this marker, the tool reopens all `.r444` and `.bc3.pvr` files from disk and checks their headers, dimensions, sizes, TXTR fingerprints and physical filenames. Missing or extra files abort preparation. fileciteturn40file1L62-L86
---
## TXTR parsing
DeltaCache parses the GameMaker container directly:
```text
FORM
↓
TXTR
```
The current implementation expects the Deltarune / GMS 2022.9 layout with 28-byte entries.
Relevant fields:
```text
+12 width
+16 height
+24 blobOffset
```
`blobSize` is calculated from the next non-zero `blobOffset`, or from the end of the TXTR chunk for the final blob.
External pages:
```text
ptr == 0
or
blobOffset == 0
```
are recorded in the manifest and do not receive external cache files. fileciteturn40file1L88-L105
---
## BC3 / PVR
DeltaCache generates a BC3/DXT5 PVR v3 file for every internal Texture Page.
The validator requires:
```text
PVR v3 magic = 0x03525650
flags = 0
pixelFormat = 11
colorSpace = 1
channelType = 0
depth = 1
numSurfaces = 1
numFaces = 1
numMipmaps = 1
dimensions = TXTR dimensions
payload size = width * height
```
These requirements match the current Runner contract. fileciteturn40file1L107-L118
### sRGB normalization
Some PVRTexToolCLI builds accept an sRGB input option but still serialize:
```text
colorSpace = 0
```
The Runner requires:
```text
colorSpace = 1
```
DeltaCache v0.3.6 normalizes the PVR v3 header after BC3 conversion while leaving the compressed BC3 payload intact, then performs the normal validation pass. fileciteturn40file0L3-L7
### BC3 color preservation (v0.3.6-r2)
The original v0.3.6 command declared the PNG input as sRGB but left the BC3
output colour space implicit. PVRTexTool defaults that output to lRGB, causing
an unwanted global gamma conversion before compression.
The corrected pipeline explicitly preserves sRGB values:
```text
-ics sRGB -f BC3,UBN,sRGB -m 1
```
BC3 is used to reduce texture VRAM consumption. It must not globally change
the artwork's brightness, saturation, or contrast. Only the small amount of
4×4 block interpolation inherent to BC3/DXT5 is expected.

---
## Runtime texture modes
DeltaCache always generates **both** representations.
The Vita Runner decides which one to use.
### Optimized
```text
BC3 only for 2048x2048 Texture Pages
R444 for everything else
```
### None
```text
R444 for every Texture Page
```
### Aggressive
```text
BC3 for every Texture Page
```
The reference selection logic is documented in `RUNTIME_SELECTION.md`. fileciteturn40file2L16-L30
---
## Runtime fallback
Recommended Runner behavior:
```text
selected representation
↓
valid cache available?
├─ yes → load it
└─ no → try alternate representation
↓
unavailable?
↓
data.win
```
When changing texture mode during gameplay, resident GPU textures should be invalidated/released so they can be recreated in the newly selected format. The cache files themselves do not need to be deleted. fileciteturn40file2L34-L49
---
## DeltaRepack workflow
DeltaCache is designed to work after **DeltaRepack**.
```text
DeltaRepack
↓
optimized data.win
↓
DeltaCache
↓
R444 + BC3
↓
DeltaruneVita
```
Always generate caches from the exact rebuilt `data.win` that will be deployed.
Do **not** mix:
```text
new data.win
+
old texture-cache
+
old pvr
```
because the TXTR offsets, sizes, dimensions and Texture Page layout may have changed.
---
## Updating between versions
The launcher can look for previous DeltaCache versions placed side-by-side and import missing files from:
```text
chapters/
source/UTMT_CLI/
source/PVRTexToolCLI/
source/renderer_reference/
```
without overwriting files already present in the newer version. fileciteturn40file1L128-L135
---
## Requirements
- Windows
- Python
- UndertaleModTool / UndertaleModCLI
- PVRTexToolCLI
- helper scripts included under `source/`
`gl_legacy_renderer.c` is no longer required to generate R444 headers in this version because the cache contract is fixed and the fingerprint fields are read directly from TXTR. fileciteturn40file1L128-L135
Do not redistribute third-party binaries unless their licenses allow it.
---
## Repository hygiene
Do not commit:
```text
chapters/*
prepared/*
```
except for placeholder/readme files used to keep the directories in Git.
If you keep local output variants such as:
```text
prepared (PTBR)/
prepared(Steam v0.0.253)/
```
they should also stay outside version control because they may contain generated game data.
A suitable `.gitignore` should exclude all of these generated/input folders.
---
## Game files
This repository must **not** contain:
- original `data.win` files
- generated `data.win` copies
- extracted commercial Deltarune assets
- generated `.r444` caches containing game texture data
- generated `.bc3.pvr` caches containing game texture data
Users must provide their own game files from a legitimate installation.
---
## Current version
```text
DeltaCache v0.3.6
```
Current v0.3.6 changes:
- fixes PVR files generated with `colorSpace = 0`
- normalizes PVR v3 to sRGB (`colorSpace = 1`)
- preserves the BC3 payload
- keeps strict dimension and payload validation
- includes automatic migration from v0.3.5 fileciteturn40file0L1-L7
---
## Related projects
### DeltaRepack
Rebuilds GameMaker Texture Pages to reduce Room working-set VRAM.
### DeltaruneVita
The PS Vita port/runtime that consumes the prepared texture caches.
---
## Disclaimer
Deltarune, GameMaker, PlayStation Vita and any related trademarks are properties of their respective owners.
DeltaCache is a community-developed tool and is not affiliated with or endorsed by those companies or rights holders.