CrunchyOS 0.6 Manual

Table of Contents:

I. Introduction
    Savings Table
II. Features
    Missing Features
III. Using CrunchyOS
IV. Level Packer Tool
V. Developer Information
    Converting to
    TI82 compatibility
VI. Technical Info about the shell
VII. Version History
VIII. Credits
IX. Contact

I. Introduction

CrunchyOS is an assembly shell for the TI83+ and TI83+SE calculators that allows you to run assembly language programs on your TI83+.  ASM programs are faster, and usually have better graphics and game mechanics than TI-Basic games.  Examples of other TI83+ ASM shells include Ion, MirageOS, and TSE.

CrunchyOS is a step above the other shells in that it supports compressed programs.  Compressed programs are far smaller then their uncompressed equivalents, at the cost of short decompression time.  Many large programs can be compressed down by factors around 50%, but most smaller games can get 10-30% size savings.

Savings Table

Here is an example of the size differences between compressed and uncompressed programs:  (program sizes may be off by up to 10 bytes)

Program Name 
Ion/MirageOS Size:
CrunchyOS Size:
Joltima 1.9
Dying Eyes 1.0
Phoenix 2.11
Lotus Turbo Challenge 1.0

II. Features

CrunchyOS has the following features:

Missing Features

The following features are missing:

III. Using CrunchyOS

First, you must install the flash application, crnchyos.8xk onto your TI83+ or TI83+ silver edition graphing calculator.  Please consult the TI-Graphlink or TI-Connect documentation for more information on sending flash applications.

Warning: Some ASM programs contain bugs that may freeze, crash, or reset the RAM of the calculator.  If you are working on any important TI-Basic projects, make sure you group or archive all your files before running an assembly program.

To start the shell, press the APPS button, then select CrnchyOS from the application list and press Enter, as shown below:
APPLICATIONS 1:Finance... 2:Bubble *3:CrnchyOS* 4:MirageOS

The program menu will appear.  CrunchyOS, Ion, MirageOS, and TI-Basic programs that begin with a colon will appear on the program list.

Use the arrow keys to move the cursor.  Up and Down move the cursor, while Left and Right advance by page.  2nd and Enter keys run the selected program.  Use Mode or Clear to quit the shell.

Programs without enough free RAM to run will be marked with an asterisk * symbol.  You will receive an error message when you attempt to run a program without enough RAM to hold the unarchived or uncompressed copy.  Delete, archive, or group programs to free up RAM space for the programs to run.
CrunchyOS 0.5b by Dwedit  Not enough free RAM to load the program.  Mem Needed: 22393  Mem Available: 15632

If you run the shell with no compatible programs on the calc, you will get the No Programs screen.  Press Clear or Mode to quit the shell, then go install some programs.
CrunchyOS 0.5b by Dwedit  No Programs!

If you run a MirageOS program that uses an unsupported MirageOS feature, you will get an error message like the one below:  (this one's from Ztris)  That error message indicates that the SetupInt function ($4191) is not supported by CrunchyOS.  ZTris will still play fine without it though.
@9DC6: CALL 4191 Not Implemented!

If your program fails, gives a TIOS error, or is turned off during a getkey, don't panic.  Your memory is safe, since the shell features memory leak protection.
For example, the calc has been shut down with 2nd+Off while running the program Afrodance, and weird symbols have appeared on the homescreen text!  Your memory is safe.  The garbage text is normal, and not an indication that your memory is corrupt.  The next time you start the shell, the temporary program "CruEXEC" that was created will be deleted (if the program was archived), or the Ion program will be repaired (if the program was in ram).

IV. Level Packer Tool

CrunchyOS includes a tool to compress external data (level) files for Ion programs.  You will need the Visual Basic 6.0 runtime libraries and ActiveX controls installed to use the program.
Level packs compressed by this program will work for any Ion or MirageOS program that uses Iondetect, but you must be using the CrunchyOS shell.

Run the program, IonLevelCompressor.exe
First, you will need to select which level sets your want to compress.  They must all be from the same game.  Click Next >>.

Then the ionDetect string length selector window displays the current IonDetect string, which may be incorrect.  Press the up and down buttons until the string is the correct IonDetect string.  If you selected multiple levels, the string should be properly autodetected, with higher accuracy for more levels selected.

Finally, the program may ask for the path to pucrunch.exe, which is included with the shell.  If it does, locate the file.
Click the Compress button to compress the selected ion levels.  Programs will not be overwritten, new programs named like LEVELc.8xp will be created.  This only renames the filename, not the on-calc name.  The c at the end of the filename is short for compressed or crunchy.

V. Developer Information

To take advantage of the compression and other features offered by CrunchyOS, you will need to write programs for the shell.

You should upgrade to TASM 3.2 final if you have not done so already.  The program is available on or my website.  It is a Win32 console program with lots of improvments over the old dos versions, like less limits on labels, and long file names.

The way I recommend to program for CrunchyOS (and all other shells) is to use the universal "" file.  This file handles all the calcs (TI82,83,83+) and all shells for each calc.  To compile for a different calc/shell combination, use a different batch file.  Get the set of batch files for use with at

Rules of CrunchyOS programming

Converting an Ion program to use

The easiest way to program for CrunchyOS is to use the universal "" include file, since it supports all the shells, including CrunchyOS.
You include "" instead of the shell specific include file.  No surprise there.
First remove all executable code before the program description. itself generates the shell-specific start code depending on which shell you compile for.  Name the start code of the program lblStart:, since looks for a line with that name.

For CrunchyOS compatibilty, the program description must be added conditionally.  First make the necessary .name file.  Then create a new line:
#ifndef CRUNCHY\tTitle: #include ""\#endif needs the program name label to be defined as tTitle:.  Only CrunchyOS needs the .name file.

Here's an example:
This is the original beginning of the source code of 7G:

#include ""
#ifdef TI83P
  .org progstart-2
  .db $BB,$6D
  .org progstart
  jr nc,start
  .db "--==7G==-- v3.0", 0
  ;start of prorgam

Make the changes...  First replace with, then remove the shell-specific start code.  Create the .name file, make the program description not show up on CunchyOS, Rename the program start label, create the conditional description.

#include ""
#ifndef CRUNCHY\tTitle: #include ""\#endif
  ;start of program

There's more.  The saved data must be marked, and the length known.  Here's the original 7G hiscore memory:

  .dw $0000
  .dw $0000
  .dw $0000
  .dw $0000
  .dw $0000

To get writeback working properly in CunrchyOS, you need to mark the start of the perminent data with a SAVE_START label, then define the length.  Subtracting the SAVE_START from current address $ is the easiest way to get the SAVE_LENGTH, as shown below:

  .dw $0000
  .dw $0000
  .dw $0000
  .dw $0000
  .dw $0000

If your program has multiple regions of data that needs to be saved, you should move the lines around so that the entire savegame is one big contiguous block.  The shell supports split savedata, but the batch file that builds the program does not.
If your program needs to perminently save self modifying code that is scattered all over the place, you should design your program differently.  CrunchyOS won't support the excessive number of short saveblocks necessary for those situations.  Redesign your program so the self-modify code can be stored to and rebuilt from a table of bytes for example.
If your program does not need to save, set SAVE_START = 0 and SAVE_LENGTH = 0.

TI82 Compatiblity

This section has nothing to do with CrunchyOS, just with porting your programs to the TI82.

For TI82 compatibilty, there are certain romcalls that need to be called with bcall(), and certain romcalls that need be called with icall().
All these romcalls should be called with icall(_romcallname) instead of bcall(_romcallname):

Use bcall() for the rest of the available romcalls:  (yes... that's it. TI82 assembly is more limited due to lack of a complete romcall list)
_GRBUFCPY    ;should be using fastcopy instead
The TI82 ACE shell also provide these additional romcalls:

If you need any of the ion functions other than ionFastcopy, you can find the code for them in "ionf.z80" that comes with ion, or "cru_ionf2.z80" that comes with this shell.  Put #IFDEF TI82 and #ENDIF around the missing ion functions, since you will not need to include them again when compiling for Ion.

Programming for CrunchyOS without using

If you don't want to bother with full range shell compatibility, then you can just modifiy your existing ion header like this:
  .org progstart+2   ;changed from -2 to +2!
Remove the BB 6D, remove the ret, jr nc lines, and remove the program description.  Move any code or data that appears before the program start further down the file.  Make the necessary .name file described previously.

Using or will work fine, just not automatically for all the calcs and shells like does.

Still not clear?

Contact me by sending me an email or IM.  My AIM screenname is Dwedit403, so contact me about CrunchyOS development issues there.

VI. Technical Info about the shell

Supported MirageOS routines:

The following MirageOS routines are implemented currently:

The rest of the MirageOS calls are not supported.  You will get error messages if you try to run them.

Header for CrunchyOS programs:

"cRu",progsize,savesize,[save1_address,save1_size],[...],description,0,raw compressed data

"cRu" (3 byte string)
Program Size (word). Program size is used by the shell for memory allocation, pucrunch doesn't need it.
Total Save Size (word). This is the total size of the appvar that will be created by the shell. A size of 0 indicates that an appvar should not be created, and there are no save blocks defined next.

For each save block:
Address of block (word). The address is inside the program, starting at $9D97.
Size of block (word).
The total sizes of the blocks must add up to the Total Size. All the sample programs have one save block. Multiple save blocks are only necessary for when the savegame split accross multiple places in the file, and you have no access to the source code to fix that.

After the save blocks:
Program Description + null terminator.

After the description:
Raw pucrunch compressed program.

The Program (that gets compressed) starts at origin $9D97 instead of $9D95, and has no description or header there, it begins with the executable code. It can use any ion function, or supported MirageOS function (MirageOS support is not yet complete).

The save blocks are all the information necessary to implement "writeback". The shell manages an appvar (with the same name as the program). On program load, it copies savegames from the appvar to the program. On program quit, it creates an appvar if it doesn't exist, then copies savegames from the program to the appvar.

The current system requires you to define labels SAVE_START, and SAVE_LENGTH. The batch file to build the program, asmcru.bat, adds .export directives, so it puts SAVE_START, SAVE_LENGTH, and PROG_SIZE into a temp.sym file. The program is compressed, then a separate header is built based on the contents of the temp.sym file. The header and compressed program are merged to a new .bin file, then that .bin file gets devpac8xed.

Format for Pucrunched Ion Levels

"pu",detectstring,size,raw compressed data

"pu" - 2 byte string literal
detectstring - This is the string that is passed to IonDetect when looking for the program
size - This is the uncompressed size of the file.
raw compressed data -  Take the source file after the detection string, compress the rest, then it goes here

Converting Ion binaries to CrunchyOS format by hand

In case you need to port a closed source ION program to the shell, just do this:
First open the .8xp file in a hex editor, and select everything AFTER BB 6D, and exclude the last 2 bytes.  Save it as a .bin file.  Replace the ion header with 0's, then remove the first 2 bytes.  This sets the execution address, and pucrunch's rle will take care of the zeroes.

Compress the thing, run Pucrunch.exe file.bin file.pu
Copy file.pu to a new .bin file

Slap on a new header:
"cRu" (3 bytes), program size (word), $0000 (word), Program Description, $00 (byte)

If you want to support save games, and know the address of the data in ram:
"cRu" (3 bytes), program size (word), savegame size (word), savegame address (word), savegame size (again), Program Description, $00 (byte)

Finally, for split savegames, you can about 7 different save blocks...
"cRu" (3 bytes), program size (word), savegame size (word), savegame part 1 address (word), savegame part 1 size (word), savegame part 2 address (word), savegame part 2 size (word)... Program Description, $00 (byte)
The sum of the saveblocks must add up the the total savegame size

VII. Version History

Version 0.1, Dec. 17, 2003

Version 0.2, Dec. 24, 2003

Version 0.3, Dec. 30, 2003

Version 0.4a, Jan. 4, 2004

Version 0.4b, Jan. 5, 2004

Version 0.5, Jan. 9, 2004

Version 0.5a, Jan. 9, 2004

Version 0.5b, Jan 13, 2004  (5 days in the submission queue at

Version 0.6, Jan 18, 2004

VIII. Credits

CrunchyOS Shell written by Dan Weiss (Dwedit) in 2003-2004.  Web:, Email:
MirageOS replacement routines disassembled by Kristopher Root, based on the original MirageOS routines created by the mirageos team.  Web:
Ion function routines by Joe Wingbermuehle.  Web:
Pucrunch compression technology created by Pasi 'Albert' Ojala.  Long rambling page about how pucrunch works:
Original Gameboy Z80 Pucrunch decompressor created by Jeff Frohwein in 1999.
The decompression routine is modified from the original GBZ80 version. First it was ported to be TASM compatible, and for a real Z80 rather than the gameboy Z80. I also modified it to run from saferam1, and to test for ROM page boundaries.

IX. Contact

You can email me at, or send an AIM instant message to Dwedit403.  I only chat about TI-calc releated stuff usually.