README_DeltaCache.md
11163 bytes · Original / download
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:
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:
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:
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
.r444caches for every internal Texture Page - Builds
.bc3.pvrcaches for every internal Texture Page - Parses
FORM -> TXTRdirectly from the finaldata.win - Uses real TXTR
blobOffset,blobSize,widthandheight - 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
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:
assets/
├─ icon.png
├─ logo_black.png
└─ logo_white.png
chapters/
Place the final data.win files here.
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:
prepare_texture_cache_v0_3_6.bat
DeltaCache scans the available chapters, parses each TXTR and prepares both texture formats.
Typical output:
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:
20-byte header
+
width * height * 2 bytes of raw RGBA4444
Header:
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:
sourceSize = blobSize
sourceOffset = blobOffset
width = TXTR width
height = TXTR height
Pixels are stored raw, without zlib compression. fileciteturn40file1L30-L45
Alpha packing
A4 = 0 if A == 0
A4 = min(15, (A + 15) >> 4) otherwise
Cache magic
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:
texture-cache/complete.vtc
Format:
uint32 completeMagic
uint32 txtr.count
Magic:
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:
FORM
↓
TXTR
The current implementation expects the Deltarune / GMS 2022.9 layout with 28-byte entries.
Relevant fields:
+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:
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:
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:
colorSpace = 0
The Runner requires:
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:
-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
BC3 only for 2048x2048 Texture Pages
R444 for everything else
None
R444 for every Texture Page
Aggressive
BC3 for every Texture Page
The reference selection logic is documented in RUNTIME_SELECTION.md. fileciteturn40file2L16-L30
Runtime fallback
Recommended Runner behavior:
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.
DeltaRepack
↓
optimized data.win
↓
DeltaCache
↓
R444 + BC3
↓
DeltaruneVita
Always generate caches from the exact rebuilt data.win that will be deployed.
Do not mix:
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:
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:
chapters/*
prepared/*
except for placeholder/readme files used to keep the directories in Git.
If you keep local output variants such as:
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.winfiles - generated
data.wincopies - extracted commercial Deltarune assets
- generated
.r444caches containing game texture data - generated
.bc3.pvrcaches containing game texture data
Users must provide their own game files from a legitimate installation.
Current version
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.