Chrono Trigger translation development system

Copypaste from the Makefile:

# VERSION 1.0.0  first archived version. dumper works.
# VERSION 1.0.1  working with recompressor, added tools.
# VERSION 1.0.2  updates to patcher
# VERSION 1.0.3  bugfixes to patcher - first working version!
# VERSION 1.0.4  handled fixed strings too
# VERSION 1.0.5  found item descriptions
# VERSION 1.0.6  compressed better
# VERSION 1.0.7  compressed more carefully
# VERSION 1.0.8  documented the script
# VERSION 1.0.9  fixed "..." handling and located the font
# VERSION 1.0.10 had knowledge of character sets
# VERSION 1.0.11 had a working font insertor
# VERSION 1.0.12 had better knowledge of special codes
# VERSION 1.0.13 used 62-base numbers
# VERSION 1.0.14 added taipus.cc
# VERSION 1.0.15 updated FIN/README and ct_fin.txt, but neither are archived
# VERSION 1.0.16 added taipus.rb, fixed homepage urls and fixed mmap error checking.
# VERSION 1.0.17 working again; uses space better; little modularized
# VERSION 1.0.18 more of above
# VERSION 1.0.19 code organising... improved 'i' in 8x8 font.
# VERSION 1.0.20 binpacker changes, some translation done too
# VERSION 1.0.21 more translation, some documentation, font palette changes.
# VERSION 1.0.22 more translation, autowrapping support, conjugation detection code
# VERSION 1.1.0  did some assembly hacking, support for code patching
# VERSION 1.1.1  conjugating conjugating conjugating... work goes on
# VERSION 1.1.2  and so on
# VERSION 1.1.3  and so on... almost working! "case" still doesn't work.
# VERSION 1.1.4  conjugating finally works!
# VERSION 1.1.5  some bugfixes
# VERSION 1.1.6  fixed an allocation bug and optimized the code generator a bit
# VERSION 1.1.7  some translation, more asm changes
# VERSION 1.1.8  syntax changes in the compiler, optimizations
# VERSION 1.1.9  support for font/dictionary size skew
# VERSION 1.1.10 new configuration system. Time to squash bugs.
# VERSION 1.1.11 configuration works, font-enhancement works.
# VERSION 1.2.0  variable-width 8pix font has stepped in, but has many many bugs.
# VERSION 1.2.1  more vwf stuff, backup before doing big changes
# VERSION 1.2.2  vwf stability++, also techniques now vwf. Scrolling bugs.
# VERSION 1.2.3  lots of more translation
# VERSION 1.2.4  8pix system deciphered, more bugs introduced
# VERSION 1.2.5  characterset enlarged by 512, only vwf8 bugs still
# VERSION 1.2.6  using nonstandard hash_map for greatly improved performance
# VERSION 1.2.7  creating another compiler
# VERSION 1.2.8  improved dictionary compression
# VERSION 1.2.9  compiler progress, first windows binaries are working
# VERSION 1.2.10 cursive font support
# VERSION 1.2.11 some translation, compression optimizations
# VERSION 1.3.0  new compression options, font reorganizer, generic typeface engine
# VERSION 1.4.0  image patching support, more font reorganizing support
# VERSION 1.4.1  lots of more translation (I'm archiving it here for my convenience)
# VERSION 1.5.0  end of the compiler project; using assembler (xa65) now.
# VERSION 1.5.1  vwf8 optimizations, assembly experiments
# VERSION 1.5.2  compressed graphics support: decompressor and compressor
# VERSION 1.5.3  better graphics compressor
# VERSION 1.5.4  another archive-only version
# VERSION 1.6.0  signature support (custom compressed image on startup screen)
# VERSION 1.6.1  some remodularizing of code
# VERSION 1.6.2  fixed the vwf8 scrolling problems and some other bugs
# VERSION 1.6.3  battle item lister fixed - no vwf8 problems there now
# VERSION 1.6.4  battle tech lister almost done; dumper: partial jap ROM support
# VERSION 1.6.5  is working on an assembler
# VERSION 1.6.6  has an almost working assembler
# VERSION 1.6.7  has a complete assembler, doesn't require xa65 anymore
# VERSION 1.6.8  patch version
# VERSION 1.6.9  conjugater now partially asm; its compiler is a separate program
# VERSION 1.7.0  some error checking; windows build of the assembler
# VERSION 1.8.0  is GPL
# VERSION 1.8.1  requires separate snescom (not bundled anymore)
# VERSION 1.9.0  unified some configuration parts; added crononick-code support
# VERSION 1.9.1  improved the signature feature; added checksum and ROM name feature
# VERSION 1.9.2  has only documentation updates
# VERSION 1.9.3  includes the forgotten snescode and dictionary modules.
# VERSION 1.10.0 implemented various assembly optimization techniques
# VERSION 1.10.1 updated the docs and the conj.code generator
# VERSION 1.10.2 creates more useful information when dumping
# VERSION 1.10.3 has technological updates but broken VWF8
# VERSION 1.11.0 has technological updates and new item list code with VWF8
# VERSION 1.11.1 adds the documentation core
# VERSION 1.11.2 is a backup before anything catastrophic happens
# VERSION 1.11.3 is another backup
# VERSION 1.11.4 is another backup again
# VERSION 1.11.5 another... big structural changes
# VERSION 1.11.6 backup copy... this version has bugs
# VERSION 1.11.7 unwraps the script when dumping, if configured so
# VERSION 1.11.8 has much more documentation than before
# VERSION 1.11.9 is faster than the few recent versions
# VERSION 1.12.0 allows some strings to be moved between pages
# VERSION 1.12.1 is an upgrade to support the new o65 extension...
# VERSION 1.12.2 fixes a bug in ctdump (battle message list not dumped properly)
# VERSION 1.12.3 fixes a bug that caused utils/codegen.cc not compile
# VERSION 1.13.0 added support for expansion to 48 Mbit or 64 Mbit
# VERSION 1.13.1 added support for free relocation of all script text
# VERSION 1.13.2 is a minor bugfix to the expansion patch
# VERSION 1.13.3 is a bugfix to the checksum fixer
# VERSION 1.13.4 is a fix to the dumper. 600ad castle texts are now again ok.
# VERSION 1.13.5 is another dumper fix, but also finishes the battle VWF8 support
# VERSION 1.13.6 is yet another fix, but also finishes the monster name code
# VERSION 1.13.7 brings an improvement to the sluggish VWF8 screens problem
# VERSION 1.13.8 C++ standard compliance upgrade... also a new eq-related feature
# VERSION 1.13.9 is a vwf8 bugfix, but seems to have other problems!
# VERSION 1.14.0 is a new "stable" release, at least for posix.
# VERSION 1.14.1 fixes the checksum generator problem and stabilizes the windows port.
# VERSION 1.14.2 fixes a bug related to Lucca's SightScope with long monster names.
# VERSION 1.14.3 supports changing the character names! Do a redump with ctdump and see.
# VERSION 1.15.0.0 preliminary support for location events.
# VERSION 1.15.0.1 improved compression. Configuration file changes.
# VERSION 1.15.0.2 improved support for location events.
# VERSION 1.15.0.3 improved location event decompiler.
# VERSION 1.15.1 location event support - preliminary release.
# VERSION 1.15.2 now dumps the button names and allows changing them.
# VERSION 1.15.2.1 conjugator supports now [member].
# VERSION 1.15.3 conjugator now supports definition by a table.
# VERSION 1.15.3.1 minor changes in conjugator for severe grammars.
# VERSION 1.15.3.2 a bugfix in ctdump (deleting the *c block). Added more documentation!
# VERSION 1.15.3.3 minor changes in default config.
# VERSION 1.15.3.4 changes in portability, documentation, and RLE IPS support.
# VERSION 1.15.3.5 drops support for Windows versions.
# VERSION 1.15.4 adds packedblob support and fixes compilation on certain platforms.
# VERSION 1.15.5 improves compilability on more modern gcc versions
# VERSION 1.15.5.1 improves compilability on more modern gcc versions
# VERSION 1.15.6 adds rawblob and spriteblob support (thanks Michal Ziabkowski)
# VERSION 1.15.6.1 improves the LZ-variant compression a little.
# VERSION 1.15.7 improves compilability on more modern gcc versions
# VERSION 1.15.8 improves compilability on more modern gcc versions

To use the character name changing feature, do a redump with ctdump and copypaste the *e, *c and *s1B blocks to your script.

Dumps the script and fonts from a given ROM.
Requires chrono-dumpee.smc.
Produces the script file, the font files and a couple of other image files.

Sample of produced script:

*z;dialog
;-----------------
;1000ad (Lucca's home)
;2300ad (factory)
;1000ad (rainbow shell trial)
;-----------------
$F1IO:
[nl]
            You got 1 [item]!
$F1IQ:
LARA: Oh, hi Crono.[nl]
   Lucca's off at Leene Square with her
   father, Taban, unveiling her new invention.
$F1IS:
LARA: Lucca and Taban only care about their silly toys!

(Dumped from the English ROM)

Usage example: ctdump chrono-uncompressed.smc

Reinserts the (edited) script and (edited) fonts to a ROM.
Requires the files referenced by ct.cfg (usually ct.txt, ct8fn.tga and ct16fn.tga, elemental images and optional extra fonts and code files).
Produces ctpatch-hdr.ips and ctpatch-nohdr.ips.
Curiously, it doesn't require the ROM.

It currently has support for conjugating names on fly.
It's very important in Finnish, where you can't just add "'s" to anything to make a genitive.
For example, genitive of name Matti is "Matin", and genitive of name Crono is "Cronon".
The conjugator-engine is a textual script file translated to 65c816 assembly on demand. It can be customized to do conjugation in any language, not just Finnish.

It's quite complicated to explain, but shortly said:

In normal Chrono Trigger, the character set is as follows:

127 of them are assigned to the dictionary used to compress the script.
96 of them are possible visible symbols.

In Chronotools,

Dictionary size may be anything between 0-223
The amount of different characters the script may use is 735 minus dictionary size.
Though, 8pix strings (items, techs, monsters, character names and so on) can only use about 128 different characters.

There are drawbacks though.

Shrinking the dictionary gives more available characters, but makes compression worse. This could cause the script not fit in the ROM.
Extracharacters (anything above 223 minus dictionary size) require twice the space of normal characters. This has similar effect as above.

Despite these hazards this system might be a lifesaver for someone doing an Estonian, Portuguese or even Thai translation.

Note: The Japanese version of the game is almost exactly the same as the English version. Both have the same engine with only minor changes. If you are going to translate to Chinese or something else that uses thousands of different symbols, you are either going to have to manage with ~700 symbols or have to request some changes to the insertor.

Expanding the character set is a complicated thing because of its configurability. Maybe less options would be better, but then it wouldn't always work.

The compression, btw, generally shrinks the raw script (which is about 2/3 of the size of ct.txt) by a factor of 30...40%.
For a 370 kB script file this means about 30 kB of free ROM space or 74 kB of free dialog text space.

The program takes automatically care of proper line lengths, so you don't have to risk running into unexpected too-long-lines or making too short lines in paranoia.
You can force line breaks (like in HTML), but you don't have to.

The image on the right shows this script piece:

Tämä on Leenen Aukio. Sanotaan, että jos
joskus kuulee Leenen Kellon soivan, elää
mielenkiintoisen ja onnellisen elämän!

And is equal to if I had wrote this:

Tämä on Leenen Aukio. Sanotaan, että[nl]
jos joskus kuulee Leenen Kellon soivan,[nl]
elää mielenkiintoisen ja onnellisen[nl]
elämän!

Item, monster and technique names in Chrono Trigger are limited to 10 characters (restriction is enforced by both the screen layout and the ROM space).
This is way too little for many languages with long words.

For this reason Chronotools creates a vwf8 engine that allows the game to draw the names in thinner font that fits on the screen.

This feature is optional and can be applied to items, techniques and monsters - each to them separately.

Note: CURRENTLY THIS FEATURE WORKS ONLY ON EMULATORS; NOT ON REAL HARDWARE, AND NOT ON MOST ACCURATE EMULATORS. Really, really sorry about that. It is never my intention to create emulator-only code, but when I made this feature, I didn't know that Snes9x didn't emulate H-DMA updates properly, and now the VWF feature is a bit too complex to fix.

If by whatever reason 32 Mbits is not enough for you, you can expand the ROM size with the romsize setting in the configuration file. Chronotools will then automatically use the extra space when needed for all relocatable objects.
Even the script can now be freely relocated if it's declared with *Z (capital Z).

However Chronotools is designed to be able to use all the built features within a 32 Mbit ROM. You only need to increase the ROM size if you're doing a jumbo translation (increasing the text amount by a big factor) or adding lots of custom images.

This is something that allows basically rewriting every scene of the game - adding new characters and objects to scenes and making them act differently.
With certain limitations though.

This feature is in its early phase and (ab)using it is not yet recommended. Its syntax may (will) also vary, meaning that your hacks would most probably not compile in the next release.

Some (technical) up-to-date documentation of interest is available here.

I have tried to put almost everything in text-only config files instead of hardcoding it in the programs. You won't be depending on me to do little updates for your purposes.

Among other things, Chronotools contains the following parts which are more or less reusable:

base16, base62 converters
LZ compressor/decompressor (no assembler versions)
configuration parser
character set handler and optimizer (very hard to separate)
conjugator engine (very hard to separate)
dictionary generator (aka. DTE compressor) (very hard to separate)
fixed-width font and image handlers (C++ code) (very hard to separate)
assembly module linker library
block-fitter (binpacking, space optimization)
cross-referencing patches, reference handling and combining (hard to separate)
XML parsing
8pix variable width font engine (very hard to separate)
font typeface generator (hard to reuse)
ROM checksum fixer
assembler, disassembler and a linker

You almost certainly need programming expertise to reuse anything of those. Before doing anything, please send me email and explain your situation.

Things that should be documented some day but currently are not:

How does the character map actually work
Known bugs and their resolutions
Script format guidelines (how do the indents work)
Tips and hints one should know
The source code

Chrono Trigger translation development system

1. Purpose

2. How to begin?

3. Current status

3.1. Version history

3.1.1. Release notes

4. Program list

4.1. ctdump

4.2. ctinsert

4.3. other

4.3.1. makeips

4.3.2. unmakeips

4.3.3. xray

4.3.4. viewer

4.3.5. sramdump

4.3.6. base62

5. Useful features

5.1. Player name inflection

5.2. Font/dictionary skew

5.3. Automatic paragraph wrapping

5.4. Variable width 8pix font

5.5. Expansion to 48 Mbit or 64 Mbit

5.6. Location event support

5.7. Very configurable

6. Summary of extra features

7. Requirements

8. Copying

8.1. Ripping my hacks

9. Documentation

9.1. Undocumented things

10. See also

Screenshots

11. Downloading