I. Introduction
Savings Table
II. Features
Missing Features
III. Using CrunchyOS
IV. Level Packer Tool
V. Developer Information
Rules
Converting to Dwedit.inc
TI82 compatibility
Without dwedit.inc
VI. Technical Info about the shell
VII. Version History
VIII. Credits
IX. Contact
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.
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: |
Savings |
|
Joltima 1.9 |
22242 |
>> |
11288 |
10954 |
(49.2%) |
Dying Eyes 1.0 |
22305 |
>> |
13881 |
8424 |
(37.8%) |
Gemini |
23872 |
>> |
13459 |
10413 |
(43.6%) |
Phoenix 2.11 |
7953 |
>> |
5774 |
2179 |
(27.3%) |
Lotus Turbo Challenge 1.0 |
10161 |
>> |
7116 |
3045 |
(30.0%) |
Total: |
86533 |
>> |
51518 |
35015 |
(40.4%) |
CrunchyOS has the following features:
The following features are missing:
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:
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.
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.
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.
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).
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.
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
ticalc.org 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 "dwedit.inc" 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 dwedit.inc at http://dwedit.tk/.
The easiest way to program for CrunchyOS is to use the universal
"dwedit.inc" include file, since it supports all the shells, including
CrunchyOS.
You include "dwedit.inc" instead of the shell specific include file. No surprise there.
First remove all executable code before the program description.
Dwedit.inc itself generates the shell-specific start code depending on
which shell you compile for. Name the start code of the program
lblStart:, since dwedit.inc 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 "progname.name"\#endif
Dwedit.inc 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 "ion.inc"
#ifdef TI83P
.org progstart-2
.db $BB,$6D
#else
.org progstart
#endif
ret
jr nc,start
.db "--==7G==-- v3.0", 0
start:
;start of prorgam
Make the changes... First replace ion.inc with dwedit.inc, 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 "dwedit.inc"
#ifndef CRUNCHY\tTitle: #include "7g.name"\#endif
lblStart:
;start of program
There's more. The saved data must be marked, and the length known. Here's the original 7G hiscore memory:
Hightooeasynb:
.dw $0000
Higheasynb:
.dw $0000
Highnormalnb:
.dw $0000
Highhardnb:
.dw $0000
Highimpnb:
.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:
SAVE_START
Hightooeasynb:
.dw $0000
Higheasynb:
.dw $0000
Highnormalnb:
.dw $0000
Highhardnb:
.dw $0000
Highimpnb:
.dw $0000
SAVE_LENGTH = $ - SAVE_START
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.
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):
_getkey
_ldhlind
_cphlde
_divhlby10
_divhlbya
_getcsc
_lcdbusy
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)
_DispHL
_Puts
_NewLine
_PutC
_Vputs
_Vputmap
_ClrLCDFull
_ClrLCDF
_GRBUFCPY ;should be using fastcopy instead
_GRBUFCPY_V
The TI82 ACE shell also provide these additional romcalls:
_lcdbusy
_chkfindsym
_createprog
_memfree
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.
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 ion.inc or mirage.inc will work fine, just not automatically for all the calcs and shells like dwedit.inc does.
Contact me by sending me an email or IM. My AIM screenname is
Dwedit403, so contact me about CrunchyOS development issues there.
The following MirageOS routines are implemented currently:
centertext
compstrs
compstrsn
cphlbc
delayb
directin
fastcopys
getbytetios
largespritehl
multhe
multhl
nextstr
putsprite8
quittoshell
rand127
sendbytetios
setpixel
setvputs
version
vputa
cphlde
The rest of the MirageOS calls are not supported. You will get error messages if you try to run them.
"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.
"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
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
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 ticalc.org...)
Version 0.6, Jan 18, 2004
CrunchyOS Shell written by Dan Weiss (Dwedit) in 2003-2004. Web: http://dwedit.tk/, Email: crunchyos@dwedit.cjb.net
MirageOS replacement routines disassembled by Kristopher Root, based on
the original MirageOS routines created by the mirageos team. Web:
http://www.greenfire.tk/
Ion function routines by Joe Wingbermuehle. Web: http://joewing.net/index.shtml
Pucrunch compression technology created by Pasi 'Albert' Ojala. Long rambling page about how pucrunch works: http://www.cs.tut.fi/~albert/Dev/pucrunch/
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.
You can email me at crunchyos@dwedit.cjb.net, or send an AIM instant message to Dwedit403. I only chat about TI-calc releated stuff usually.