Encyclopedia

Reference for ZScripter 4.2.0

support@zscripter.com

For support, include your app version, iOS or iPadOS version, device model, game title, and steps to reproduce the issue.

Importing

Choose a game folder, archive, or executable. The format is detected automatically.

Tap + to choose From Files, Web Importer, or Import Help. For split RAR or 7z archives, keep every part together and choose the containing folder.

Folder Import

NScripter Family

Recognized Root Markers

0.txt
00.txt
0.u
00.u
0.utf
0.utf.txt
00.utf
00.utf.txt
nscr_sec.dat
nscript.___
nscript.dat
pscript.dat

Place a recognized script marker at the game root. Loose resources and NSA or SAR resource archives may sit beside it.

Typical Layout
Game/
├── 0.txt
├── arc.nsa
├── arc1.nsa
└── default.ttf
Alternative Layout
Game/
├── 0.utf
├── pscript.dat
└── arc.sar

RealLive

Recognized Root Markers

Gameexe.ini + Seen.txt
KINETICDATA/
REALLIVEDATA/

Gameexe.ini + Seen.txt at the root or in an immediate KINETICDATA/REALLIVEDATA folder; names are case-insensitive. Keep all referenced resources and relative paths. AVG32, Siglus, and wrapper-only .ezk/.ezs packages are unsupported.

Typical Layout
Game/
├── Gameexe.ini
├── Seen.txt
├── G00/
├── BGM/
├── WAV/
└── KOE/
Alternative Layout
Game/
└── KINETICDATA/ (or REALLIVEDATA/)
    ├── Gameexe.ini
    ├── Seen.txt
    └── … resources

Ren’Py

Recognized Root Markers

game/ → *.rpy
game/ → *.rpyc
game/ → *.rpa
game/ → RPA data.bin
data/ + renpy/__init__.py

Use a game directory containing scripts or RPA data. Legacy data directories require a sibling Ren’Py engine marker; packaged Mac app layouts are discovered automatically.

Typical Layout
Game/
├── game/
│   ├── script.rpyc
│   └── archive.rpa
└── renpy/
Packaged Mac Layout
Game.app/
└── Contents/Resources/autorun/
    ├── game/
    └── renpy/

Engine Package Import

Beta engine reference. KiriKiri imports are not available in App Store distribution.

KiriKiri

startup.tjs
System/Initialize.tjs
XP3-backed root
Executable-appended XP3
ZIP-backed root
TAR-backed root
7-Zip-backed root

Loose roots, XP3-backed roots, executable-appended XP3, and verified generic containers with one unambiguous embedded startup root are accepted.

Archive File Import

ZIP

.aab
.apk
.apkm
.apks
.ipa
.xapk
.zip

ZIP and ZIP64, including APK, AAB, APKS, XAPK, APKM, and IPA game packages. Supports stored, Deflate, and supported LZMA entries. Encrypted entries are not supported.

RAR

.rar

RAR 4 and RAR 5, including supported self-extracting archives, .partNN.rar sets, and legacy .rar + .r00 sets.

7-Zip

.7z

7z archives with LZMA or LZMA2 data, including raw split .7z.001 multipart sets.

LHA/LZH

.lha
.lzh

LHA/LZH header levels 0–3; LH0–LH7, LHD, LZS, LZ4, and LZ5 methods; Japanese CP932 filenames. Supported self-extracting packages use level 0 or 1 headers.

TAR

.tar

Uncompressed TAR, including v7, ustar, pax, and GNU variants.

TAR.XZ

.tar.xz
.txz
.xz

TAR streams filtered with XZ.

TAR.GZ

.gz
.tar.gz
.tgz

TAR streams filtered with GZip/DEFLATE.

TAR.BZ2

.bz2
.tar.bz2
.tbz
.tbz2

TAR streams filtered with BZip2.

Executable Import

Self-extracting game archives

ZIP
RAR
LHA/LZH

Supported ZIP, RAR, and LHA/LZH packages can be selected directly. Game data is extracted without running the executable.

Inno Setup

5.1.2
5.3.9
5.3.10
5.4.2
5.5.0
5.5.6
6.0.0
6.1.0
6.7.0

ANSI layouts through 5.5.6 and Unicode layouts from 5.3.9 onward. Stored, zlib, bzip2, LZMA1, and LZMA2 payloads.

NSIS

NSIS 2.x-style header layout

ANSI and Unicode filenames; non-solid and solid Deflate or LZMA payloads. Solid bzip2 and LZMA with a BCJ filter are not supported.

Enigma Virtual Box

Embedded VFS
Stored payloads

Embedded file systems whose files are stored without compression.

Back to sections
Supported Engines

NScripter / ONScripter / PONScripter

Runtime Dialects

NScripter
ONScripter
PONScripter

ONScripter Forks

ONScripter
ONScripter-EN

PONScripter Fork Profiles

Original / Mion (2011)
Sekai Project Steam
Witch Hunt (1x)
Witch Hunt (2x)
07th-Mod v3
07th-Mod v4

Automatic detection is the default. A profile can be selected per game when a fork’s behavior cannot be inferred reliably.

Script Formats

0.txt
00.txt
0.utf
00.utf
nscript.dat
nscript.___
nscr_sec.dat
pscript.dat

KiriKiri

Beta engine reference. KiriKiri imports are not available in App Store distribution.

Runtime Families

KiriKiri 2
KiriKiri Z
Hybrid / unknown compatibility profile

RealLive

Game files

Gameexe.ini + Seen.txt
Seen.txt: 10002 · 110002 · 1110002
CP932 · CP936 · Windows-1252 · CP949

Resource formats

G00 · PDT · ANM · GAN · HIK
WAV · NWA · Ogg Vorbis
KOE · NWK · OVK

Save containers

saveNNN.sav.gz
global.sav.gz
Save folders
ZIP archives (.zip)
ZScripter save bundles (.json)

Ren’Py

Ren’Py 6.15

2 exact releases

6.15.4
6.15.7

Ren’Py 6.17

4 exact releases

6.17.3
6.17.4
6.17.6
6.17.7

Ren’Py 6.18

1 exact releases

6.18.3

Ren’Py 6.99

19 exact releases

6.99.1
6.99.3
6.99.4
6.99.5
6.99.6
6.99.7
6.99.8
6.99.9
6.99.10
6.99.11
6.99.12
6.99.12.2
6.99.12.3
6.99.12.4
6.99.13
6.99.14
6.99.14.1
6.99.14.2
6.99.14.3

Ren’Py 7.0

1 exact releases

7.0.0

Ren’Py 7.1

3 exact releases

7.1.0
7.1.1
7.1.3

Ren’Py 7.2

3 exact releases

7.2.0
7.2.1
7.2.2

Ren’Py 7.3

5 exact releases

7.3.0
7.3.2
7.3.3
7.3.4
7.3.5

Ren’Py 7.4

12 exact releases

7.4.0
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
7.4.9
7.4.10.2178
7.4.11.2266

Ren’Py 7.5

5 exact releases

7.5.0.22043001
7.5.0.22051201
7.5.0.22062402
7.5.1.22070801
7.5.3.22090809

Ren’Py 7.6

3 exact releases

7.6.0.23051307
7.6.1.23060707
7.6.3.23091805

Ren’Py 7.7

2 exact releases

7.7.0.24012702
7.7.1.24030407

Ren’Py 7.8

2 exact releases

7.8.2.24090902
7.8.4.24120703

Ren’Py 8.0

7 exact releases

8.0.0.22052902
8.0.0.22062402
8.0.1.22070801
8.0.2.22081402
8.0.3.22083102
8.0.3.22090405
8.0.3.22090809

Ren’Py 8.1

8 exact releases

8.1.0.23042213
8.1.0.23050201
8.1.0.23051307
8.1.1.23060707
8.1.2.23072301
8.1.2.23081503
8.1.2.23090503
8.1.3.23091805

Ren’Py 8.2

7 exact releases

8.2.0.23100201
8.2.0.23121803
8.2.0.24012702
8.2.1.24030407
8.2.2.24060703
8.2.2.24061201
8.2.3.24061702

Ren’Py 8.3

10 exact releases

8.3.0.24071306
8.3.0.24082114
8.3.1.24090601
8.3.2.24090902
8.3.3.24111502
8.3.4.24120703
8.3.6.25022803
8.3.7.25031702
8.3.8.25042301
8.3.8.25051901

Ren’Py 8.4

8 exact releases

8.4.0.25052403
8.4.0.25071206
8.4.1.25071908
8.4.1.25072401
8.4.2.25073104
8.4.2.25082401
8.4.2.25111201
8.4.2.25111701

Ren’Py 8.5

12 exact releases

8.5.0.25110801
8.5.0.25111603
8.5.1.25122301
8.5.1.25123106
8.5.2.26010301
8.5.3.26012801
8.5.3.26021801
8.5.3.26031801
8.5.3.26032401
8.5.3.26043002
8.5.3.26051504
8.5.4.26061901

Ren’Py 8.6

1 exact releases

8.6.0.25112601
Back to sections
Compatibility

RealLive

Compatible

AIRStandard Edition · +Voice1.02
CLANNADOriginal PC release
KanonStandard Edition · All Ages
Little Busters!リトルバスターズ! · Original PC release
planetarian ~the reverie of a little planet~planetarian ~ちいさなほしのゆめ~ · Package Edition

NScripter family

Compatible

40 Days and 40 Nights of Rain
A Dream of Summer
A Happy Valentine
A Midsummer Day’s Resonance
A Winter’s Tale
Agnus Dei
ArcadiaArcadia -阿卡迪亞-
At Summer’s Endなつのおわりに
Ballad of an Evening Butterfly
Black Blood黑血
Bluebird’s Illusion
Eternity永遠
Exile Gear Raynar
FLOOD OF TEARS
From the Bottom of the Heart
Higurashi When They Cryひぐらしのなく頃に
Hitokazoe人数え
Instant Death! Panda Samurai
Its your last chance in new school
Kagetsu Tohya
Ki ni Naru Otokonoko?きになるおとこのこ?
Kira ~snowdrop~
LEAVEs
May Sky
Moonshine
My Black Cat私の黒猫
Narcissu
Night of the Forget-Me-Nots
OMGWTFOTL
Plain Song
Plumerai
Pray [Apocripha/0 Hot Springs]Pray [Apocripha/0 溫泉物]
Red Shift常世の星空
SALAMANDER
Shooting Star Hill
Tenshi no Oshigoto -their wishes afterward-天使のお仕事 -their wishes afterward-
The Boy I Like? 2すきなおとこのこ?
The Caged Vagrant
The Letter
The Little Prince
The Moon to the East, the Sun to the West ~Operation Sanctuary~月は東に日は西に ~Operation Sanctuary~
The noose
The Poor Little Birdかわいそうな小鳥
The world to reverse.
Tsukihime月姫
Umineko no Naku Koro niうみねこのなく頃に
Umineko no Naku Koro ni Chiruうみねこのなく頃に散
Visions from the Other Side向日の夢
Wanderers in the Sky空の迷い人
~Plain Song~ Christmas Special
Back to sections
Save snapshots

A save snapshot is a copy of all a game's stored saves, including persistent data. It records progress already saved by the game.

Create a snapshot

Open Storage from the library toolbar and choose a game. Create Snapshot Now creates a manual snapshot. The Storage menu can create snapshots for all games at once. Save in the game and close it before making or restoring a snapshot.

View the save timeline
A snapshot's actions in the save timeline. Open full-size image

Automatic snapshots

Automatic snapshots are on by default, with 10 per game, taken before launch. The other trigger checks when you open or return to the app, at most once every 24 hours per game. Empty or unchanged saves are skipped.

Save Snapshot Defaults in the Storage menu sets the trigger and a limit of 1 to 100 automatic snapshots per game. You can also turn automatic snapshots off. A game's Save Snapshot Settings can override these defaults. The oldest automatic snapshots are removed when the limit is exceeded. Manual and recovery snapshots stay until deleted.

Restore saves

In a game's Save Timeline, open a snapshot's menu and choose Roll Back to This Snapshot. This replaces all current saves, including files added since that snapshot. The app first keeps the current saves in a Before Rollback snapshot, which can undo the restore.

Manage snapshots

The timeline shows each snapshot's date, reason, file count, and size. Sort it by date or size. A snapshot's menu can export a ZIP or delete the snapshot. Deleting a snapshot leaves current saves in place.

Snapshots stay on this device. Export a copy to keep it elsewhere. After a game is deleted, its snapshots remain under All Snapshots & Archives in the Storage menu.

Back to sections
Save editor

The save editor changes Ren'Py save slots and persistent data, such as gallery unlocks shared across playthroughs.

Choose a file

Close the game, open Storage in its options, then choose Save Editor from the menu at the top right. Select a .save slot or the persistent file. If the list is empty, save in the game once or import a save.

View the save editor
Save fields with their types and values. Open full-size image

Find a value

Search by field name, value, type, or path. Filters narrow results by type or hide internal fields. Open lists and dictionaries to browse their entries; use the path buttons to go back. A field's menu can copy its value or path.

Complete Pickle Graph opens additional data, including rollback history. Document Details shows signature status. Both are in the menu at the top right.

Edit values

Edit numbers or text directly, or toggle true/false values. Use a field's menu to change its type. Dictionary keys can be renamed, and entries can be removed. Add Value inserts entries or empty containers. It can also refer to an existing object.

Undo and Redo step through pending edits. Discard All Edits clears them.

Apply changes

Open Review Changes, then choose Save Changes. The app first creates a Before Save Edit snapshot. Restore it from the Save Timeline to undo a saved edit.

The game may overwrite edited values after loading or using rollback. Invalid values can prevent a save from loading. Some files and fields allow inspection only.

Back to sections
Controllers

ZScripter uses controllers recognized by iOS or iPadOS. Available buttons and actions depend on the controller and game engine.

Supported controllers

FamilyModels
PlayStationDualShock 4
DualSense
DualSense Edge
XboxWireless Controller (Bluetooth, model 1708)
Series X|S Wireless Controller
Elite Wireless Controller Series 2
Adaptive Controller
Nintendo SwitchPro Controller
Joy-Con (L/R)
MFi and mobileBackbone One (iPhone-compatible models)
Other MFi gamepads

Other controllers can work when iOS or iPadOS recognizes them as gamepads. Compatibility and available buttons depend on system and controller firmware versions.

Connect a controller

Pair the controller through Bluetooth or connect it by cable. In app Settings, open Controls, choose an engine, then open Hardware Controller. With a controller connected, the diagram shows live input in green and dims unavailable controls. You can configure a preview layout without a controller.

View controller settings
The controller diagram and the selected button's assignment. Open full-size image

Assign buttons

In Custom Bindings, tap a button in the diagram, then its action under Selected Control. All Controls lists the available bindings. Select by Pressing a Button lets you choose a control using the controller itself.

Changes save automatically and apply to all games using that engine. Touch control layouts have separate settings.

Ren'Py input modes

Native Gamepad uses a compatible Ren'Py game's own controller bindings. Older runtimes fall back to your saved custom bindings. Switch to Custom Bindings to assign game actions or use a stick as a mouse.

Adjust sticks and triggers

Sticks & Sensitivity lets each stick act as direction buttons, a mouse cursor, or scrolling input. A stick can also be turned off. Increase the dead zone to reduce drift; adjust speed and the response curve to change how movement feels. Horizontal and vertical movement can be inverted.

Trigger Press Point sets how far a trigger must travel. Direction buttons can repeat while held, with adjustable delay and interval. Restore Controller Defaults resets bindings and stick settings for the selected engine.

Back to sections
Translation

Translation is a beta feature for Ren'Py games. It translates dialogue and menu text. Words drawn into images stay unchanged.

Turn on translation

Open a Ren'Py game's details and choose Translation. Set the source and target languages, then turn on Enable translation. Use App Settings follows the provider selected under Translation in app Settings; turn it off to choose a provider for this game. While playing, open Translation from Game Settings to adjust these settings.

View provider settings
API key and model settings for a cloud provider. Open full-size image

Choose a provider

Apple translates on the device and requires iOS 18 or later on a physical iPhone or iPad. Use Download Language Models in the game to prepare both languages. Once installed, supported language pairs work offline.

Gemini, OpenAI, DeepSeek, and OpenRouter require an internet connection and your own API key, set under Translation in app Settings. After you allow cloud translation, the provider receives game text and dialogue context. Provider usage charges apply. The in-game panel offers translation styles and custom instructions. Permission can be revoked in translation settings.

Read and compare

Original shows the source text; Translated shows the translation in the game. Compare adds a panel with both versions. Drag its header to move it, or its bottom edge to resize it.

Translate ahead prepares upcoming dialogue to reduce waiting. Cloud providers also receive that text, which can increase usage. If a translation fails, the original remains visible; use Retry Translation to try again.

Clear saved translations

Clear Translation Cache removes this game's saved translations. They are generated again as you play. Language settings and Apple's downloaded models are kept.

Back to sections
Patches

KiriKiri

Beta engine reference. KiriKiri imports are not available in App Store distribution.

Patch Bundle Files

.tjs — startup, filter, bootstrap, and override scripts
.xp3 — patch archive
.cf / .key / .cfg / .ksc — filter and auxiliary data
.zip / .7z — auxiliary archives inside catalog bundles

Plug-in Request Files

*.dll — request alias only
plugin-catalog/catalog.json — alias-to-target map
Back to sections