View source for ICE:Using ICE

[[File:169974952.png]]

= Welcome, Links =

Welcome to our introduction and tutorial to ICE Compiler. This guide will start out with the basics and continue into the more complex uses and commands of ICE. This guide is for ICE version 2.X, you can view which version of ICE you have by reading the top text line inside of the ICE program on your calculator.<br />
ICE’s Cemetech topic for questions and bug reporting is here: [https://www.cemetech.net/forum/viewtopic.php?t=12616 ].<br />
The latest version of ICE will likely be available to download from here: [https://www.cemetech.net/programs/index.php?mode=file&path=/84pce/asm/programs/ICECompiler.zip ].<br />
Every command in ICE is listed and documented here: [http://htmlpreview.github.io/?https://github.com/PeterTillema/ICE/blob/C-version/documentation/commands.html ]. Bookmark and/or print those, you will very likely need them.

= Introduction to ICE =

ICE Compiler is a C program created by the talented Peter Tillema, known on Cemetech as an administrator with the username [https://www.cemetech.net/forum/profile.php?mode=viewprofile&u=10064 <code>PT_</code>]. ICE allows you to create advanced programs right on your 84+ CE without using TI’s slow, restrictive language that is known as TI-BASIC.<br />
The way it works is simple, you make a program on your calculator using the standard TI-OS program editor, and use ICE to compile your program into eZ80 assembly, A.K.A raw machine code for your calculator. This means that your ICE programs will run much faster than TI-BASIC programs.<br />
ICE uses its own programming language that has a few similarities to TI-BASIC, but has a vastly more complex programming system packed with features that allow you to make the most of your calculator. Full graphics controls, raw memory editing, lots of variables, and much more.<br />
However, by using ICE, you can put your calculator and its data at risk. The ICE language is powerful, and allows you to create more advanced programs than TI-BASIC would ever allow, but it also allows you to freeze your calculator, cause RAM resets, corrupt data, and other dangers. When you decide to use ICE, be ready for whatever mistake you may make. Make backups, try to use an [https://github.com/CE-Programming/CEmu ] if possible, and thoroughly check your code.


= Installing ICE =

Putting ICE onto your calculator is very simple and can be completed in just a few steps:

<ol>
<li><p>Download the ICECompiler.zip file from the GitHub releases page (see section 1).</p></li>
<li><p>Extract the .zip file you just downloaded using a program such as Bandizip, winRAR, 7zip, or similar.</p></li>
<li><p>If using your physical calculator, send <code>ICE.8xp</code> and <code>ICEAPPV.8xv</code> to your TI-84+ CE using [https://education.ti.com/en/products/computer-software/ti-connect-ce-sw ]</p></li>
<li><p>If using CEmu, drag and drop <code>ICE.8xp</code> to the right half of the screen (labeled "RAM"), then drag and drop <code>ICEAPPV.8xv</code> to the left half of the screen (labeled "Archive").<br />
(In both cases, make sure ICE is sent to RAM, and ICEAPPV is sent to the archive.)</p></li>
<li><p>Run ICE at least once so it can set itself up. If you are '''not''' using OS 5.3 or newer, you must use the <code>Asm(</code> token found in the catalog, <code>[2nd]</code>,<code>[0]</code> before the program name to run an assembly program like ICE. Like this:<br />
</p>
<p>[[File:Runice.png|image]]</p>
<p>If you '''are''' using OS 5.3 or newer, you can just omit the <code>Asm(</code> token and run it like any other program.</p></li></ol>

<br />
You’ll likely be greeted by a message saying ICE didn’t find any programs to compile, this is expected as you don’t yet have ICE programs. Hit <code>[Clear]</code> to exit ICE and return to the TI homescreen. You may see a few strange graphical artifacts on your homescreen, these are just harmless artifacts, just hit <code>[Clear]</code> on the TI homescreen to clean them up.


Now that you have set up ICE, you are ready to begin creating ICE programs.


= Making an ICE program =

An ICE program is created like any other, from the homescreen on your calculator. Hit <code>[Prgm]</code>, <code>[->]</code>, <code>[->]</code>, <code>[Enter]</code>. Give the program a name, and hit <code>[Enter]</code>.<br />
Right now that program doesn’t do anything and ICE won’t do anything to it. Because ICE compiles programs into assembly and stores the assembly into another program, you need to specify the name of the other program the compiled code will be put into.<br />
To give your ''compiled'' program a name, place an imaginary ''i'', <code>[2nd]</code>, <code>[.]</code>, on the very first line of your source program. This fancy ''i'' is called an ’Imaginary’ and from now on will be referred to as <code>[i]</code>.<br />
Directly after <code>[i]</code>, type in a name for the program this will be compiled into. It must follow the standard program naming scheme; starts with a letter, is all capital letters or numbers, no more than 8 characters.

{|
|

| '''Note: In ICE, when <code>[i]</code> is used at the beginning of any line other than the first,'''
|-
|

| '''it signifies a comment line. ''Everything'' typed onto a comment line after <code>[i]</code> will'''
|-
|

| '''be ignored by ICE and not get compiled into the final program. You may use this'''
|-
|

| '''to create notes in your source code for yourself or to temporarily disable lines of'''
|-
|

| '''code for debugging purposes.'''
|}


An example of a comment and a name:<br />


[[File:Iceprog.png|image]]

Editing your ICE program can be done inside your calculator’s program editor, or you can instead use Cemetech’s online IDE, [http://sc.cemetech.net ]. SourceCoder3 has full ICE support, and it’s much easier to write code on a computer. SourceCoder3 allows you to type in all of ICE’s custom functions, graphics, and file I/O function names, and have the output automatically converted to the correct tokens. It also features syntax highlighting and indenting, giving you a nice organized look for your programming environment.<br />


[[File:SourceCoder3.PNG|image]]

If you plan on using sprites and/or tilemaps, we ''highly'' recommend you use SourceCoder3, because it makes it much easier to paste in sprite/tilemap hex codes that you will need for graphical applications..<br />
You can also transfer already existing programs between SourceCoder3 and your calculator.

== Icon, description ==

If you have used [https://www.cemetech.net/programs/index.php?mode=file&id=1372 ] before, you might have noticed that some programs have their own icon and description. It is possible to give your programs an icon and description with ICE too!<br />
Right after the header with the output name (the first line), put another line, starting with the imaginary ''[i]'' followed by a 16x16 pixel icon. This icon should begin and end with a " and consist of 256 hexadecimals.<br />
You can make an icon with all 14 of the OS colors. Press <code>[VARS]</code>, <code>[\leftarrow]</code> to get a list with all the OS colors, and convert the number before the color to a hexadecimal.<br />
If you are using SourceCoder3, you can switch the program type to CSE TI-BASIC, and type a ". This will open up a sprite editor. Create a new 16x16 sprite and start editing! This will automatically insert the hexadecimals, so you don’t have to do that manually.<br />
If you want to add a description too, add a new line after the icon line, that also starts with the imaginary ''[i]'', and then the description, without quotes.

[[File:Icon1.png|image]] [[File:Icon2.png|image]]<br />
[[File:Icon3.png|image]]

== <code>[Trace]</code> Menu ==

Because a calculator can only have so many different tokens before it becomes an inefficient use of space, all of ICE’s graphics functions are a <code>det(</code> token, and all of ICE’s I/O functions are a <code>sum(</code> token, both with a number in it as a command index. Because all these numbers are difficult for a human to keep track of, ICE installs a useful feature into TI’s program editor. If you hit <code>[Trace]</code> while inside a calculator’s program editor, you will be greeted by a list of commands.<br />
This menu includes the full names of ICE’s commands as well as all of ICE’s custom tokens and the syntax of each command/token. Use the left/right arrow keys to browse through the various pages of the list, and up/down arrow keys to move your cursor. Hit <code>[Enter]</code> to paste the selected command, or <code>[Clear]</code> to leave the menu without modifying anything.<br />
Another feature that ICE implements to make it easier for you to keep track of the commands, is a "tooltip" that appears in the second line of the status bar, showing the full name and the syntax of the command. This tooltip automatically appears if you place your text caret (the black, blinking rectangle) over the beginning of a <code>det(</code> or <code>sum(</code> command.<br />


<code>[Trace]</code> menu (left) and caret tooltip (right):

<br />


[[File:Trace.png|image]] [[File:Hover.png|image]]

<br />


{|
|

| '''Note: ICE has to have been run on your calculator at least once since the last'''
|-
|

| '''reset for these features to work.'''
|}

== Compiling ==

When you are ready to run your program, you need to run ICE and select the name of your source program from the list. ICE can compile program regardless of whether they are archived or in RAM.<br />


{|
|

| '''Note: ICE will only show programs that have the proper <code>[i]</code> header. If you do not'''
|-
|

| '''see your source program in the list, double check your header is correct. If you'''
|-
|

| '''have more than 22 programs with an ICE header, a few may not be visible on screen.'''
|}


Once you hit <code>[Enter]</code> on your program, ICE will begin compiling. Depending on the size of your program, this may take less than a second or multiple seconds. If ICE encounters an error in your program, you will be given an error message explaining the type of error, and the line the error was encountered on. If your source program is unarchived, ICE will open the program editor and go to the line containing the error.<br />


[[File:Error.png|image]]

If there are no errors in your program, ICE will give you a "compiled successfully" message and will exit when you hit a key.<br />


[[File:Succes.png|image]]

You may then run the compiled program (using the <code>Asm(</code> token if you are not using OS 5.3+). It’s possible that at some point, your program will crash. When your programs have problems '''after''' being compiled, it is up to you to figure out the mistake you made in your program and to fix it. If you’re having trouble, or are you sure that you did nothing wrong, be sure to ask for help on Cemetech (ICE’s forum linked in the first section.)

= Math &amp; Numbers =

ICE’s math works just about how you would expect it to from any programming language, you have the four standard operators:

{|
|align="center"| +
|align="center"| Addition
|-
|align="center"| -
|align="center"| Subtraction
|-
|align="center"| *
|align="center"| Multiplication
|-
|align="center"| /
|align="center"| Division
|}

You can use these operators in your math expressions and ICE will compile them in the correct order (see [[#OOO|5.4]]). ICE will also automatically simplify expressions when compiling to save space in the final program.<br />
The next subsections go over the specifics of mathematics and numbers in ICE.

== Positive Integers ==

ICE only supports positive integers. This means no negative numbers, no decimals, and no fractions. The most directly affected operation by this is division. Division will always return a truncated answer, meaning that anything after the decimal point (and the decimal point itself) is simply omitted (truncated). For example:

{|
! '''Expression'''
! '''Returns'''
! '''Explanation'''
|-
| {\color{red}10}/{\color{blue}3}
| <span>3</span>
| {\color{red}10}/{\color{blue}3}\approx3.33, truncated = <span>3</span>.
|-
| {\color{red}84}/{\color{blue}52}
| <span>1</span>
| {\color{red}84}/{\color{blue}52}\approx1.62, truncated = <span>1</span>.
|-
| {\color{red}8}/{\color{blue}3}
| <span>2</span>
| {\color{red}8}/{\color{blue}3}\approx2.67, truncated = <span>2</span>.
|-
| {\color{red}7}/{\color{blue}12}
| <span>0</span>
| {\color{red}7}/{\color{blue}12}\approx0.58, truncated = <span>0</span>.
|}

If you try to compile a program that includes a decimal point or a fraction, you will get a "<code>This token/function is not implemented (yet)</code>" error.<br />
Due to ICE only having positive integers, the negative sign works differently than it does normally. It works by taking 16777216 (2^{24}) and subtracting the number after the negative sign.

{|
|

| '''Note: Remember that there is a different key for a'''
|-
|

| '''negative sign than the key for a subtraction sign.'''
|}


{|
! '''Expression'''
! '''Returns'''
! '''Explanation'''
|-
| -{\color{red}85}
| <span>16777131</span>
| 16777216 - {\color{red}85} = {\color{green}16777131}
|-
| -{\color{red}9000000}
| <span>7777216</span>
| 16777216 - {\color{red}9000000} = {\color{green}7777216}
|-
| -{\color{red}(2*8)}
| <span>16777200</span>
| 16777216 - {\color{red}(2*8)} = {\color{green}16777200}
|}

== 3-byte Numbers ==

ICE uses 3 bytes, or 24 bits, to store all numbers and perform mathematical operations. This means the biggest number you can have is 2^{24} - 1, so 16,777,215. You cannot have more than this number. If you go over this number, you get what is known as ’rollover’. This means your result will be modulo 16777216 (the remainder when you divide by 16777216). An example of this is:<br />


16777215 + 10 = 9

That equation went over the 3-byte limit, so it ’rolled over’(looped back around) to 0, then continued the operation. The same can happen backwards,<br />


0 - 10 = 16777206

Later in this guide we will introduce you to some control over whether a number is stored in 3-byte, 2-byte, or 1-byte.

== Not Implied Multiplication ==

Multiplication is never implied. Remember how in TI-BASIC you could have <code>10A</code> in your program and it would be interpreted as <code>10*A</code>? This was because TI-OS would automatically add a multiplication sign in between the 10 and A. ICE, for reasons we will cover later, doesn’t do that. You must always type a multiplication sign when you want to multiply. This includes when using parentheses.<br />


{|
| 8(12+4)
|align="center"| <span>Incorrect</span>
| 8*(12+4)
|align="center"| <span>Correct</span>
|-
| 15A
|align="center"| <span>Incorrect</span>
| 15*A
|align="center"| <span>Correct</span>
|-
| ABC
|align="center"| <span>Incorrect</span>
| A*B*C
|align="center"| <span>Correct</span>
|-
| 5(AG)(7*8)
|align="center"| <span>Incorrect</span>
| 5*(A*G)*(7*8)
|align="center"| <span>Correct</span>
|}


== Order of Operations ==

If you made it through middle school, you (hopefully) know of the mathematical order of operations, known as <code>PEMDAS</code>. This simple string of letters tells us the order in which we do math when we come across an expression with more than one operation in it. ICE properly follows this order. For those who don’t remember, the order is:


{|
| '''P'''arentheses
|align="center"| Do what is inside parentheses first.
|-
| '''E'''xponents
|align="center"| Solve the exponents (this includes roots.)
|-
| '''M'''ultiplication and '''D'''ivision
|align="center"| Both at the same time, from left to right.
|-
| '''A'''ddition and '''S'''ubtraction
|align="center"| Both at the same time, from left to right.
|}


This means that if ICE comes across 8+(40-7*2), it will do 7*2, then 40-\textbf{14}, then 8+\textbf{26}.

== Modifiers ==

There are two little modifiers you can use with constants in your ICE programs:<br />


# Scientific E (<span>E</span>). You can paste this in by hitting <code>[2nd]</code> <code>[,]</code>. When this is placed directly before a constant, ICE will convert the constant from hexadecimal to decimal when compiled.
# Pi (\pi). You can paste this in by hitting <code>[2nd]</code> <code>[^]</code>. When this is placed directly before a constant, ICE will convert that constant from binary to decimal when compiled.

== Mathematical Functions ==

ICE supports a few of the math functions you can find in TI-OS (though a few have different syntax), they are:<br />


{|
! '''Function'''
! '''Explanation'''
|-
| <code>remainder(EXP1,EXP2)</code>
| Returns the remainder when <span>EXP1</span> is divided by <span>EXP2</span>.
|-
| <code>min(EXP1,EXP2)</code>
| Returns the smaller value of <span>EXP1</span> and <span>EXP2</span>.
|-
| <code>max(EXP1,EXP2)</code>
| Returns the larger value of <span>EXP1</span> and <span>EXP2</span>.
|-
| <code>mean(EXP1,EXP2)</code>
| Returns the mean (average) value of <span>EXP1</span> and <span>EXP2</span>.
|-
| <code>sqrt(EXP)</code>
| Returns the square root of <span>EXP</span>.
|-
| <code>sin(EXP)</code>
| Returns the sine root of <code>EXP</code>. Input <code>EXP</code> should be a value between
|-
|

| 0 and 255 (split the circle into 256 equal sections) and will return a
|-
|

| value between -255 and 255.
|-
| <code>cos(EXP)</code>
| Returns the cosine root of <code>EXP</code>. Input <code>EXP</code> should be a value
|-
|

| between 0 and 255 (split the circle into 256 equal sections) and will
|-
|

| return a value between -255 and 255.
|}


{|
|

| '''Note: All results will be truncated.'''
|}


'''Examples:'''

{|
! '''Code'''
! '''Returns'''
! '''Explanation'''
|-
| <code>remainder(10,3)</code>
| <span>1</span>
| <span>3</span> goes into <span>10</span> only 3 whole times, with <span>1</span> leftover.
|-
| <code>remainder(64,10)</code>
| <span>4</span>
| <span>10</span> goes into <span>64</span> only 6 whole times, with <span>4</span> leftover.
|-
| <code>remainder(10,5)</code>
| <span>0</span>
| <span>5</span> goes into <span>10</span> ''exactly'' 2 whole times, with <span>0</span> leftover.
|-
| <code>min(5,2)</code>
| <span>2</span>
| <span>2</span> is ''less'' than <span>5</span>.
|-
| <code>min(123,120)</code>
| <span>120</span>
| <span>120</span> is ''less'' than <span>123</span>.
|-
| <code>min(10,10)</code>
| <span>10</span>
| <span>10</span> is ''equal'' to <span>10</span>.
|-
| <code>max(5,2)</code>
| <span>5</span>
| <span>5</span> is ''greater'' than <span>2</span>.
|-
| <code>max(123,120)</code>
| <span>123</span>
| <span>123</span> is ''greater'' than <span>120</span>.
|-
| <code>max(10,10)</code>
| <span>10</span>
| <span>10</span> is ''equal'' to <span>10</span>.
|-
| <code>mean(22,20)</code>
| <span>21</span>
| ({\color{red}22}+{\color{blue}20})/2={\color{green}21}
|-
| <code>mean(64,20)</code>
| <span>42</span>
| ({\color{red}64}+{\color{blue}20})/2={\color{green}42}
|-
| <code>mean(5,8)</code>
| <span>6</span>
| ({\color{red}5}+{\color{blue}8})/2=6.5, truncated = <span>6</span>.
|-
| <code>sqrt(25)</code>
| <span>5</span>
| \sqrt{\color{red}25}={\color{green}5}.
|-
| <code>sqrt(120)</code>
| <span>10</span>
| \sqrt{\color{red}120} \approx 10.954, truncated = <span>10</span>.
|-
| <code>sqrt(2)</code>
| <span>1</span>
| \sqrt{\color{red}2} \approx 1.414, truncated = <span>1</span>.
|-
| <code>sin(2)</code>
| <span>12</span>
| 255*sin({\color{red}2}/256*2*\pi)\approx12.51, truncated = <span>12</span>.
|-
| <code>sin(120)</code>
| <span>49</span>
| 255*sin({\color{red}120}/256*2*\pi)\approx49.75, truncated = <span>49</span>.
|-
| <code>sin(255)</code>
| <span>16777210</span>
| 255*sin({\color{red}255}/256*2*\pi)\approx-6.26, truncated = <span>-6</span>.
|-
| <code>cos(2)</code>
| <span>254</span>
| 255*cos({\color{red}2}/256*2*\pi)\approx254.69, truncated = <span>254</span>.
|-
| <code>cos(120)</code>
| <span>16776966</span>
| 255*cos({\color{red}120}/256*2*\pi)\approx-250.10, truncated = <span>-250</span>.
|-
| <code>cos(255)</code>
| <span>254</span>
| 255*cos({\color{red}255}/256*2*\pi)\approx254.92, truncated = <span>254</span>.
|}

== Binary ==

This subsection covers the binary number system, so if you already know how that works, feel free to skip this section. If you plan on using the more advanced features of ICE, such as bitwise operators (covered below), you’ll need to have an understanding of how numbers are stored in computers as bytes and bits of binary.<br />
In our standard decimal number system, there are ten different characters, zero through nine. When we put multiple of these characters together into one number, the order of these numbers from right to left signifies how big each place is, going by powers of ten starting at zero.<br />
For example, in the number 5124, the farthest right number (number 4) is the smallest, having only ten to the power of zero amounts per value. If you look at the character to the left (number 2), you now have a value that has ten to the power of one, amounts. Look left again (number 1), and you have ten to the power of two amounts.<br />
This means that the amount, 5124, is compromised of 4 amounts of one (10^0), 2 amounts of ten (10^1), 1 amount of a hundred (10^2), and 5 amounts of a thousand (10^3).<br />
To get the amount for each place, you take the amount of characters in the number system, ten for decimal, and power it to the place the character is in going from the right.<br />
In binary, however, there is only ones and zeroes, so only two characters. That means that each place in a binary number is an amount of a power of two. Take the following number for example:<br />


<code>001101</code>

Now let’s convert it into decimal so we can actually understand what value that number represents. Starting from the right-most place, 1 (the digit in the place) times 2^0 (the amount of the place) gives us 1. Now we continue to the left.<br />
In the second place from the right, we have a 0, which means no value, so we can ignore this and continue to the left. In the third place we have a 1, so we multiply 1 by 2^2 (power of two because this is the second place after the right-most place). 1 times 4 is 4, and we add the previous values, 1+4 is 5.<br />
Look left once more and we have another 1, so we multiply 1 by 2^3 (power of three because this is the third place after the right-most place). 1 times 8 is 8, and we add the previous values, 5+8 is 13.<br />
The rest of the numbers to the left are zeroes, so we ignore them. After that tedious process, we have 13. So binary <code>001101</code> is equal to decimal 13.

== Bitwise operators ==

Normally, all the math you do in ICE modifies bytes at a time; this makes sense, as each number is represented by one, two, or three bytes. However, there are situations in which you’d want to modify values by one bit at a time. Each byte is made up of 8 bits, each bit is either a 1 or a 0. When a bit is 1, it is considered to be "set", otherwise it is considered to be "reset". The action of changing a bit to it’s opposite (changing a 1 to a 0 or a 0 to a 1) is called "flipping".<br />
The right-most bit of a byte is bit 0, the one to the left of that is bit 1, to the left of that is bit 2, etc.<br />
These situations are where you would want to use bitwise operators. The bitwise operators are plot style tokens, which you access from the bottom of the catalog (<code>[2nd]</code>, <code>[0]</code>), below the inequality signs. They look like a miniature plus sign, a square outline, and a dot. The three tokens are as follows:

{|
|align="center"| <code>EXP1</code> <code>+</code> <code>EXP2</code>
|align="center"| Bitwise OR of <code>EXP1</code> and <code>EXP2</code>
|-
|align="center"| <code>EXP1</code> <code>\cdot</code> <code>EXP2</code>
|align="center"| Bitwise AND of <code>EXP1</code> and <code>EXP2</code>
|-
|align="center"| <code>EXP1</code> <code></code> <code>EXP2</code>
|align="center"| Bitwise XOR of <code>EXP1</code> and <code>EXP2</code>
|}


In the terminology we just gave you:<br />
Bitwise OR is used to '''set''' bit(s).<br />
Bitwise AND is used to '''reset''' bit(s).<br />
Bitwise XOR is used to '''flip''' bit(s).<br />
They look like this in the catalog:<br />


[[File:BitwiseOps.png|image]]

If you’re already familiar with binary or you read the previous subsection, you know that each bit in binary data is a power of two. The right-most bit is 2^0 (1), the bit left of that 2^1 (2), left once more is 2^2 (4), etc. This is important to know for bitwise operators, because you need to know what the values you are using look like in binary.<br />
Say for example that you wanted to flip bit 4 of the three byte value, <code>4233</code>, which looks like this:<br />


<code>000000000001000010001001</code>

Because we want to <code>flip</code> bit '''4''' of <code>4233</code>, we must use the bitwise <code>XOR</code> operator with two to the power of '''4''', which looks like this:

<code>4233  16 -> A</code>


We used 16 after the bitwise XOR because 2^4 = 16. The result of the A in the example is 4249, which looks like this:<br />


<code>000000000001000010011001</code>

It may not be very apparent right now, but bitwise operators are more useful when you’re dealing with memory and pointers.


= Variables =

In ICE, you have variables just like any most other programming languages, you can read their values, store values into them, and use them in expressions. Remember that ICE still only supports 3-byte numbers.<br />


{|
|

| '''Note: The "->" symbol in this document is the STORE character, you type this by'''
|-
|

| '''pressing the button just left of 1, <code>[STO->]</code>.'''
|}

== Multi-Letter Variables ==

Variables in ICE work very similarly to TI-BASIC, but they’re better and you have more of them. Instead of single-letter variables in TI-BASIC such as A or X, ICE lets you have any variable name, up to 10 characters, as long as the entire name is made out of CAPITAL letters. Examples:<br />


<code>1999/32->APPLES</code>

<code>98*2->FRANK</code>

<code>42->MEANING</code>

<code>2*FROG->LION</code>

You may still use single characters as variables if you wish. By default, all variables are stored with 3-bytes.<br />


{|
|

| '''Note: You can use up to 85 variables!'''
|}

== Chained Store ==

In TI-BASIC, if you wanted to store the same value to multiple variables, you would have to write the initial value multiple times like this:<br />


<code>42->A</code>

<code>42->B</code>

<code>42->C</code>

<code>42->D</code>

<code>40->E</code>

In ICE, you can instead chain the whole thing together on one line:<br />


<code>42->A->B->C->D-2->E</code>

It saves a few bytes and makes your code less cluttered. (It also works with multi-letter variables, of course.)

== Lists ==

Lists in ICE a very different to lists in TI-BASIC, mainly because of ICE’s pointers. You can no longer store data directly into lists using <code>{1,2,3,4,5}->L1</code> and instead have to use the <code>Copy()</code> and/or <code>CopyData()</code> commands to load data into lists. <code>CopyData()</code> allows you to copy data from one place to another (hence the name), and when used with lists can be used to emulate TI-BASIC list syntax. The syntax for <code>CopyData()</code> is:<br />


<code>CopyData(DESTINATION,SIZE,DATA1,DATA2,...)</code>

With <span>DESTINATION</span> being a memory address, and <span>SIZE</span> being the size in bytes for each entry, all other arguments are the data that is to be copied into the destination. Using this to store {1,2,3,4,5} into L1 would look like this:<br />


<code>CopyData(L1,3,1,2,3,4,5</code>

This has one small detail you’ll need to understand. The second argument in the example above, 3, says that each entry will be copied as a 3-byte number.

The size of each entry in a list is very important to how you will access data from a list. There are many different ways to access data from a list, but these are the main 5:

* <code>L1(X)</code>
* <code>{L1+X}</code>
* <code>\ast\negmedspace\ast\negmedspace\ast{L1+X}</code>
* <code>\ast\ast{L1+X}</code>
* <code>\ast{L1+X}</code>

The first three work exactly the same way and are just different ways of typing it out, they access the Xth byte, the Xth+1 byte, and the Xth+2 byte, and return them as a single number. This means that if your list has 3-byte entries in it and you want to access one of those 3-byte entries, you want to use a multiple of 3 in your command. So let’s say you previously used the example command, CopyData(L1,'''3''',1,2,3,4,5), accessing your list after this would look like:


{|
| <code>L1(0)</code>
| <code>{L1+0}</code>
| <code>\ast\negmedspace\ast\negmedspace\ast{L1+0}</code>
| '''All''' return 1.
|-
| <code>L1(3)</code>
| <code>{L1+3}</code>
| <code>\ast\negmedspace\ast\negmedspace\ast{L1+3}</code>
| '''All''' return 2.
|-
| <code>L1(6)</code>
| <code>{L1+6}</code>
| <code>\ast\negmedspace\ast\negmedspace\ast{L1+6}</code>
| '''All''' return 3.
|-
| <code>L1(9)</code>
| <code>{L1+9}</code>
| <code>\ast\negmedspace\ast\negmedspace\ast{L1+9}</code>
| '''All''' return 4.
|-
| <code>L1(12)</code>
| <code>{L1+12}</code>
| <code>\ast\negmedspace\ast\negmedspace\ast{L1+12}</code>
| '''All''' return 5.
|}

Notice how the numbers you are putting inside the parentheses are '''multiples of 3, starting at 0'''. This is because the <code>L1(X)</code> method of accessing a list returns 3-byte numbers. If you were to use <code>CopyData(L1,2,1,2,3,4,5)</code> instead of the previous command, you would then store that data into list 1 as 2-byte entries, and then have to use:


{|
| <code>\ast\ast{L1+0}</code>
| Returns 1.
|-
| <code>\ast\ast{L1+2}</code>
| Returns 2.
|-
| <code>\ast\ast{L1+4}</code>
| Returns 3.
|-
| <code>\ast\ast{L1+6}</code>
| Returns 4.
|-
| <code>\ast\ast{L1+8}</code>
| Returns 5.
|}

Now notice that to access '''2'''-byte data from a list, you need to use curly brackets with '''two''' asterisks before them, and '''multiples of 2, starting at 0'''.<br />
Lastly, if you were to use <code>CopyData(L1,1,1,2,3,4,5)</code> instead of the previous command, you would then store that data into list 1 as '''1'''-byte entries, and then have to use:


{|
| <code>\ast{L1+0}</code>
| Returns 1.
|-
| <code>\ast{L1+1}</code>
| Returns 2.
|-
| <code>\ast{L1+2}</code>
| Returns 3.
|-
| <code>\ast{L1+3}</code>
| Returns 4.
|-
| <code>\ast{L1+4}</code>
| Returns 5.
|}

For that list of 1-byte data, you need to use curly brackets with '''one''' asterisk before them, and '''multiples of 1, starting at 0'''. The point here is, when storing data in 3-byte, you need to use multiples of 3 starting at 0 to access data with <code>L1(X)</code>, <code>{L1+X}</code>, or <code>\ast\negmedspace\ast\negmedspace\ast{L1+X}</code>. When storing data in 2-byte, you need to use multiples of 2 starting at 0 to access data with <code>\ast\ast{L1+X}</code>. When storing data in 1-byte, you need to use multiples of 1 starting at 0 to access data with <code>\ast{L1+X}</code>.<br />
If in doubt, just use 3-byte values as they will give you the largest range of values (0-16777215), but if you’re an optimizing type of person, use the smallest byte sizes anywhere you can, just remember:<br />


3-byte = 0 through 16777215

2-byte = 0 through 65535

1-byte = 0 through 255

If you’re still confused on how <code>L1(X)</code> works, remember that X is the offset, in bytes, from the beginning of the list. So because <code>L1(X)</code> accesses 3-byte values, you need to use offsets of multiples of 3, otherwise you’ll be reading 3 bytes in between two values.<br />


{|
|

| '''Note: Each list has a total size limit of 2000 bytes.'''
|}

== Strings ==

In ICE, you can store a string into any of the 10 string vars (Str0 through Str9) using the standard syntax: <code>"THIS IS A STRING"->Str1</code>. You also have the <code>length()</code>, <code>sub()</code>, and <code>+</code> commands that work similarly to how they would in TI-BASIC:<br />
<code>length()</code> returns the length, in characters, of the string you give it:<br />


<code>length("ALPHABET")</code> returns 8.

<code>"SOMETHING"->Str1:length(Str1)</code> returns 9.

<code>sub()</code> cuts out part of a string, puts it into temporary memory, and returns a pointer to it. Proper usage would be: <code>sub(STRING,OFFSET,SIZE)</code>.<br />
With <span>STRING</span> being either a string variable (Str0-Str9) or a string on it’s own ("EXAMPLE"), <span>OFFSET</span> being the amount of characters to skip before beginning the cut, and <span>SIZE</span> being the length of the cut, in characters, starting from the offset. (If you wish to start cutting from the beginning of a string, you may use 0 as an offset).<br />
With the pointer, you can read the temporary memory and put it back into a string. Remember that all strings in memory are null-terminated (simply meaning that their end is signified by a 0 byte).<br />
<code>+</code> concatenates two strings:<br />



{|
| <code>"SOME"+"BODY"->Str1</code>
| Str1 would then be "SOMEBODY".
|-
| <code>"BODY"+"SOME"->Str3</code>
| Str3 would then be "BODYSOME
|-
| <code>Str1+" ONCE TOLD ME"->Str0</code>
| Str0 would then be "SOMEBODY ONCE TOLD ME"
|}

Besides using the standard syntax of <code>"STUFF"->Str1</code>, you can also place a string (text in quotes) at a part of your program, and it will be compiled into your program’s code with its pointer returned. For example, when ICE reads <code>"PINEAPPLE"->A</code>, the binary data for "PINEAPPLE" will be compiled into your final program and its pointer will be stored into A. With this, you can later use <code>Copy()</code> commands to read from strings stored in your program code.<br />
If you place a string token on its own, without storing anything to it, it will return the memory address of the string. You can use this in commands that require a pointer to a string or for other purposes. The only exception for this is when using a string in a <code>Disp</code> command.<br />


{|
|

| '''Note: Each string variable has a total size limit of 2000 bytes.'''
|}

=== Squishing hexadecimals ===

Sometimes you will see that ICE automatically squished the string. This means that if the string consists only of hexadecimals (0-9, A-F), it automatically replaces 2 hexadecimals with the right byte, so the hexadecimals "B" and "9" will be replaced with the byte $B9, or 185 in decimal. This is done because you can’t input every single byte with TI-BASIC tokens, and it’s needed for some routines, like <code>DefineSprite(</code> or <code>SetPalette(</code>. If the string is automatically squished, but you still want to use the hexadecimals, use the single apostrophe instead of the double apostrophe (or quote). This is valid because the characters of the hexadecimals are the same as the tokens. Squishing is disabled with <code>DefineSprite(</code>, so if you have a lot of sprites in a subprogram, you don’t have to worry that you get tons of messages saying the string is squished.

== Degree Modifier ==

There is a modifier you can use in ICE called the degree symbol (). You can paste this in by hitting [2nd] [apps], [Enter] (or [1]). When this is placed ''directly'' before a '''variable''', it will return the memory address of where the variable is stored. Some commands require you use this, and you will see the documentation using them when required. This modifier does not work with strings or lists, only named variables.


= Standard System Commands =

The system section of the ICE commands list contains a few of the tokens available in the program editor. This section quicky goes over the commands and their use, in slightly more detail than the ICE command list gives.

== getKey, getKey(X) ==

<code>getKey</code> works like it does in TI-BASIC, it returns the keycode of the last pressed key, or a 0 if no key was pressed since the last inquiry. However, the keycodes are different than the TI-BASIC keycodes. Your ICE download should contain an image showing the keycodes, but you may also find it [https://i.imgur.com/vwJJYRe.png ]. An example of its use:

<pre>Repeat K=9
getKey->K
End</pre>
That simple code will just wait until the user hits [Enter].<br />
<code>getKey</code> has another variation, <code>getKey(X)</code>. The difference is that <code>getKey(X)</code> returns a 1 if the key with the keycode you give it has pressed, 0 if released. It’s much faster than <code>getKey</code> and it allows you to directly read the current state of a button, meaning that it’s more useful for games where you need to constantly do something as the user holds down a key.<br />
Example:<br />


<pre>While getKey(2)
X+1->X
End</pre>
That code continues increasing the value of X for as long as the user holds down left arrow.

== rand ==

<code>rand</code> is simple, you put it somewhere, and it gives you a pseudo-random number between 0 and 16777215. Pseudo-random means that the number is not ''completely'' random, because computers cannot actually generate random values, they instead take a starting number (called the seed) and apply a bunch of operations to it and spit out another number. Example:<br />


<code>rand->A</code>


<code>A</code> could now be 64, it could be 7777, who knows? It’s random!

== Asm() ==

The <code>Asm()</code> token, found in the Catalog ([2nd] [0], you’ll see it on the 7th line) directly inserts assembly code into the location of where the <code>Asm()</code> token would be in the final program. You give it the assembly code in the form of hexadecimal, all of the code inside the parentheses. This is useful if you have a particular assembly routine you’d like to use in your program, or if you just need to do something that ICE can’t do.

== AsmComp() ==

The <code>AsmComp()</code> token, found in the Catalog ([2nd], [0], you’ll see it on the 8th line) tells ICE to compile another ICE program, the name of which is inside the parentheses. The subprogram should not have the <code>[i]</code> header, and will be compiled into the location of the <code>AsmComp()</code> token. This can be used if you have a large ICE program you want to split into parts or if you have a lot of sprites in your program that you’d like to avoid editing. The sub-programs can also be archived, ICE will still compile them. Example:<br />


<code>AsmComp(ZSPRITE)</code>


That would compile a program called <code>ZSPRITE</code> into ICE.

== Pause ==

The <code>Pause</code> token on it’s own works how it does in TI-BASIC, it will pause the program until the user hits <code>[Enter]</code>, and then continue. You also have the option to put a number after it, which will make it pause for that amount of milliseconds (there are 1000 milliseconds in one second). Examples:<br />


<code>Pause 200</code><br />
<code>Pause 1000</code><br />
<code>Pause</code>


The first line waits for 200 milliseconds (\frac{1}{5} of a second), the second line waits for 1000 milliseconds (1 second), and the final line waits for the user to press <code>[Enter]</code>

== prgm ==

If you have just a standard <code>prgm</code> token with a program name after it, your compiled program will execute the TI-BASIC program, and any errors that are encountered will be ignored. Use this if you want to run a TI-BASIC program you have from ICE. ICE execution continues as normal when the TI-BASIC program errors or ends.

== Return, ReturnIf ==

ICE programs normally exit when execution reaches the bottom (end) of the program code, but if you need to end a program from somewhere else, you can use the <code>Return</code> token, available in the [Prgm] CTL menu from a program editor. When program execution reaches a <code>Return</code> token, the program ends as normal. There is also a <code>ReturnIf</code> token, Just place an <code>If</code> token directly after a <code>Return</code> token, with all your conditions after both tokens. This token is basically an <code>If</code> statement combined with a <code>Return</code> token. ReturnIf will evaluate the conditions you give it, and only return if the conditions return true (anything other than 0).<br />
<code>Return</code> and <code>ReturnIf</code> also have one more use in ICE: to return from a <code>Call</code> token (see next subsection).

== Goto, Lbl, Call ==

The <code>Goto</code> and <code>Lbl</code> tokens work the same way they do in TI-BASIC, <code>Lbl</code> defines a point in the program with a name, and <code>Goto</code> will jump to the assigned label and continue execution from there. Label names can consist of up to 10 random characters.<br />
ICE also gives you a <code>Call</code> token, available from the [Trace] menu in the program editor. The <code>Call</code> token will go to a label, and continue executing until it hits a return token or the end of the program, then will jump back to the original <code>Call</code> token and continue from there. This means that you can have sub-routines in your program that can be used to save space if you find yourself using the same snippets of code over and over. Example:

<pre>rand->A
If A&gt;1000
Call SOMETHING
End
Goto OTHER
Lbl SOMETHING
A*238->B
Return
Lbl OTHER</pre>
Although a very simple example, it shows the point. The example generates a random number, stores it into <code>A</code>, then checks if <code>A</code> is greater than 1000. If so, it then calls the "SOMETHING" label, from there it multiplies <code>A</code> by 238 and stores the result into <code>B</code>, and returns from the call. Then it jumps to the "OTHER" label and continues program execution. (In the example case, the program ends because there is nothing after the "OTHER" label)

== ''i'' ==

If there is a <code>[i]</code> token at the beginning of a line in your program, other than the first line, the line will be completely ignored by ICE when compiling. This means that you can comment out code for debugging purposes, or to leave yourself comments so you can understand what your own code is for.


= Program Flow Control =

Just like in any other programming language, ICE has loops and if statements that allow you to control the flow of your program. There are a few tiny differences between TI-BASIC’s use and ICE’s use of the control statements, so we’ll quickly go over the statements:

== If, Else ==

If statements check the condition code given to them, if the condition evaluates to false (0), the code inside the <code>If</code> statement does not execute, otherwise, the code executes. If the statement has an <code>Else</code> token before the <code>End</code> token, the code inside the <code>Else</code> statement will be executed. The difference here in ICE is that ICE does not have a <code>Then</code> token. To make a comparison to TI-BASIC, this means that all <code>If</code>’s in ICE ’automatically’ have a <code>Then</code> after them, meaning that all <code>If</code> statements in ICE must be paired with an <code>End</code> token. Example:

<pre>rand->A
ClrHome
If A&gt;6400
Disp "A IS GREATER THAN 6400"
Else
Disp "A IS &lt;= 6400"
End</pre>
The example generates a random number and stores it into <code>A</code>, then checks if <code>A</code> is greater than 6400. If <code>A</code> is greater than 6400, the code inside the If-Else block will be executed, meaning a string is displayed to the screen. If <code>A</code> is not greater than 6400 (if it’s equal to or less than 6400), the code inside the Else-End block will be executed, displaying <code>"A IS &lt;= 6400"</code> to the screen.

== Repeat ==

Repeat loops run the code in their block once, then evaluate the condition code, and if the condition code returns false (0), the code in their block will be run again. Each time the statement repeats, the condition code will be checked. The loop will continue indefinitely until the condition evaluates to true. Example:

<pre>0->A
Repeat A&gt;1000
A+1->A
End
ClrHome
Disp A</pre>
The example stores 0 into <code>A</code>, and then continually adds 1 to <code>A</code> until <code>A</code> is more than 1000. Of course, this is an incredibly inefficient way of doing <code>1001->A</code>, but it’s for example purposes.

== While ==

<code>While</code> is the close sibling of <code>Repeat</code>. The difference here is, the condition is evaluated at the beginning of the loop, instead of at the end like <code>Repeat</code>. Another difference is that <code>While</code> checks for code to be true (any number other than 0) to run the loop. You can use <code>Repeat</code> if you want the code inside it to be run at least once, and you can use <code>While</code> if you want the code inside it to run only when the condition evaluates to true (and for however long the condition evaluates to true). Example:

<pre>0->A
While A&lt;16777000
rand->A
End</pre>
The example stores 0 into <code>A</code>, and then continually stores a random number into <code>A</code>, until the number is greater than or equal to 16777000. Once again, inefficient code but it’s for example purposes.

== For( ==

The <code>For(</code> token is used to repeat code a certain amount of times, while using a variable as a counter. It must be paired with an <code>End</code> and has two different syntax forms, the second with a minor difference. The first one is <code>For(VAR,START,END)</code>, with <code>VAR</code> being the variable to use in the loop, <code>START</code> being an expression stating the starting value of <code>VAR</code>, and <code>END</code> being an expression stating the ending value of <code>VAR</code>. A <code>For(</code> loop will first store the starting entry in <code>VAR</code> and check if <code>VAR</code> is now greater than <code>END</code>. If <code>VAR</code> is not greater than <code>END</code>, the code in it’s loop will be run. At the end, <code>VAR</code> is incremented by 1, and the greater than check is done again. The loop will continue repeating until <code>VAR</code> is greater than <code>END</code>.<br />
The second syntax form of <code>For(</code> is <code>For(VAR,START,END,INCREMENT)</code>. <code>VAR</code>, <code>START</code>, and <code>END</code> are the same as in the first syntax form, and the <code>INCREMENT</code> is an expression that will be added to <code>VAR</code> at the end of each loop. That allows you to increment the counter by more than just one at a time. If you use a negative '''constant''' (no vars, as this is done at compile time) for <code>INCREMENT</code>, the loop will continue until <code>VAR</code> is <code>END</code>. Example:

<pre>For(A,1,20
ClrHome
Disp A
Pause 200
End</pre>
The example will first display 1 to the screen, then pause for 200 milliseconds (\frac{1}{5} of a second), and continue through the loop, displaying the value of <code>A</code> as it increments. After it displays 20 to the screen, the program exists as the loop finishes and there is no more code after the loop.


= Pointers =

Pointers can be difficult for newcomers to programming to understand, but once you understand how to properly use them, they are an incredibly powerful tool to have in your programming toolbox.<br />
Pointers allow you to read and write data to your calculator’s RAM and archive, giving you the ability to modify almost anything in your calculator’s memory. You can use their ability to cheat a high score on [https://www.cemetech.net/programs/index.php?mode=file&id=1314 ], or to simply edit the name of a program.<br />
But before we tell you how to use them, a warning: If you’re not careful with pointers and write the wrong data to the wrong address in memory, you not only risk freezing your calculator, but there is a chance of you corrupting data, breaking the OS, or worse (although unlikely), permanently damaging your calculator. Be cautious and be sure you know what you’re doing when messing with pointers. Once again, if possible, use an [https://github.com/CE-Programming/CEmu ].<br />
We’ll begin with a prerequisite, memory addresses. Every single byte of RAM and flash (archive) has a number bound to it, known as a memory address. If you want to read or write from a specific byte, you need to know it’s memory address. If you treat a variable as a memory address, you then have a pointer. Here is an example:<br />


<code>15958016->A</code>

<code>\ast{A}->SEC</code>

In the example above, we stored the number 15958016 into A, then we used <code>\ast{A}</code> to read one byte from the memory address that A points to, 15958016, and stored the read value into the variable <code>SEC</code>. 15958016 is the memory address for a byte of memory that is part of the real-time clock. Reading from this value gives you the current second. When you want to read from a memory address, there are four main ways to do so:


{|
| <code>{VAL}</code>
| Reads a word (3-byte) value from location <span>VAL</span>.
|-
| <code>\ast\ast\ast{VAL}</code>
| Reads a word (3-byte) value from location <span>VAL</span>.
|-
| <code>\ast\ast{VAL}</code>
| Reads a 2-byte value from location <span>VAL</span>.
|-
| <code>\ast{VAL}</code>
| Reads a 1-byte value from location <span>VAL</span>.
|}

The first two are exactly the same, the first is just easier to remember while the other makes it more clear that you are reading a 3-byte value. <span>VAL</span> can be an expression, a variable, or a constant (you can even put pointers inside of pointers). You may recognize these from section 6.3 on lists, because when you are reading from a list, you are reading from it’s memory address plus an offset.<br />
As for uses of pointers, if you find some other documentation, you can find memory addresses that give you useful information you could use in your programs, like the date or time. Some documentation can be found on [http://wikiti.brandonw.net/index.php?title=Category:84PCE:Ports:By_Address ] wiki. That page contains links to different ports on the TI 84+ CE, just note that you can only access (from ICE) the ones that are memory mapped. [http://wikiti.brandonw.net/index.php?title=84PCE:Ports:8000 ] is a page with ports for the real-time clock in the 84+ CE. Near the top of the page it says '''Memory-mapped address:''' F30000, this means that you can read from these ports as if they were memory by using the F30000 address range. Below you find a list of specific ports. If you wanted to read the current hour count, that page lists it as port 8008. You simply modify the memory mapped address to get F30008. Before you can use this in a pointer, you need to convert it from hexadecimal. Luckily, ICE has a modifier just for that, the scientific <span>E</span>. With this, you should now be able to read the current hour and store it into, for example, <code>A</code>, like this:<br />


<code>\ast{EF30008}->A</code>

Now you can use that hour however you wish to in your program.


= Graphics =

ICE gives you the ability to use most of the [https://github.com/CE-Programming/libraries/releases ], in your programs, and one of these libraries is <code>GraphX</code>. <code>GraphX</code> gives you full control of the calculator’s screen, allowing you to draw sprites, lines, rectangles, triangles, text, and more.<br />
As you can likely guess, this library is incredibly useful for creating games or any program that includes a GUI.<br />
This section will go over the specifics of each of the commands, and provide examples.

== Starting &amp; ending the graphics canvas ==

Before you can use any of the fancy commands that let you draw cookies, you need to setup the graphics canvas for use with <code>GraphX</code>. Luckily, that’s incredibly easy to do. Near the beginning of you program, before '''any''' of the graphics functions are used, place a single <code>det(0</code> command.<br />
When your program is executing and it hits <code>det(0</code>, the LCD is setup for use with the <code>GraphX</code> commands, and it clears the screen (sets every pixel to 0xFF (white by default)).<br />
Because TI-OS uses a different LCD mode, you can’t use the <code>GraphX</code> functions without having setup the graphics canvar with <code>det(0</code> at some point.<br />
<br />
Before your program ends (or before it runs a TI-BASIC program that does anything graphically) you need to setup the graphics canvas for TI-OS, which is also simple. Just use <code>det(1</code> before your program ends or before you run the graphical TI-BASIC program.<br />
If you don’t end the GraphX canvas and setup for TI-OS before your program ends, TI-OS will look like this:<br />


[[File:halfres.png|image]]

ICE will give you a warning if you forgot the <code>det(0</code> or <code>det(1</code>, which makes it even harder to forget. If this happens to you by accident, just turn your calculator off and back on, no need for a reset.

== Color Palettes ==

Each color you’ll use has it’s own index number you use to reference the number, and <code>GraphX</code> uses an 8-bit color palette, meaning you have 256 unique colors (numbers 0 through 255). The default palette is the xLIBC palette, as shown below, with the default colors and their corresponding index number (in both decimal and hexadecimal):<br />
[[File:rgbhlpalette.png|image]] You can find the full image [http://dcs.cemetech.net/images/rgbhlpalette.png ]. You will use the index numbers in every command that asks for a color. You can set your own color pallete by using the <code>SetPalette(</code> or <code>det(4</code> command. For creating a custom palette, see section 14.1. If you wish to reset the palette back to it’s default after setting your own, you can use <code>SetDefaultPalette(</code> or <code>det(3</code>.

== Clipping ==

Most of the graphics commands in <code>GraphX</code> have two variants, the standard one and a duplicate with "_NoClip" tacked on to the end of the name. This is because the standard commands use clipping to check if what’s being drawn is inside the current clip region. By default, the clip region is the entire screen (320x240 pixels). The <code>_NoClip</code> variants of commands are faster but can cause memory corruption or other strange problems if you accidentally tell one to draw something that outstreches the bounds of the screen.<br />
You can set a custom clip region using <code>SetClipRegion(</code>. This sets a specific area to be the clipping area. Every clipped graphics command will only draw within this area, and ignoring anything outside. This is useful when you want to update a smaller part of the screen.


= Sprites =

To use sprites in ICE, you’ll need to use a tool to convert from our source images into the ICE format we need. The tool is called <code>ConvPNG</code>, and can be downloaded from [https://github.com/mateoconlechuga/convpng/releases/latest ]. Make sure you download the correct version for your computer’s operating system.

== Creating Sprites ==

Sprites are images that you can display using ICE. In order to convert your images to a format ICE can use, you need to first download ConvPNG [https://github.com/mateoconlechuga/convpng/releases]. Place the executable in the same directory as your images. The next step is to create a file named <code>convpng.ini</code>. Be sure that the '''<code>.ini</code>''' extension is correct, and not <code>.txt</code>.

Inside of the <code>convpng.ini</code> file, place the following lines: 

<pre>#GroupICE            : ice_gfx
#Palette             : xlibc
#PNGImages           :
 image1
 image2</pre>

Replace the last two lines <code>image1</code> and <code>image2</code> with the names of the png images you created earlier, and are in the same directory as <code>convpng.ini</code>. If you have more or less images, simply add and remove lines as necessary.

Once you are done, save and close <code>convpng.ini</code> and double click on the convpng executable to run it. Or you can execute directly from the command line.

For more information on using ConvPNG, simply read the provided readme  here [https://github.com/mateoconlechuga/convpng/blob/master/readme.md].

== Loading Sprites ==

If you open the output file from the previous subsection, <code>ice_gfx.txt</code>, you will see a width, height, and long string of hexadecimals for each sprite you converted. These are the arguments that you need to give <code>DefineSprite(</code> to use the sprites in your ICE program. For each sprite, place a <code>DefineSprite(</code> token in your ICE program and copy the corresponding line of text into the token (this is why we recommend you use SourceCoder3, it makes it significantly easier to get the sprite data into your ICE program).<br />
In order to use the sprites you’ve put into your program, you need to save the pointer that <code>DefineSprite(</code> returns, so store the result to a variable. Example:<br />


<code>DefineSprite(2,2,"00FFFF00"->A</code>


This code creates a small <span>2</span> pixel wide, <span>2</span> pixel tall sprite, and stores the returned pointer into variable <code>A</code>. If we wanted to display this sprite to the screen at X-Y coordinates (<span>20</span>, <span>50</span>), we would use:<br />


<code>det(57,A,20,50</code>


<code>det(57</code> is the ICE command for <code>Sprite()</code>, which draws a clipped sprite to a given X,Y at the screen (or buffer). We can also define an ’empty’ sprite, with random data in it, which can be used for creating a sprite from the screen (or buffer). To make an empty sprite, you simply define a sprite without data, like this:<br />


<code>DefineSprite(WIDTH,HEIGHT)</code>


The example still returns a pointer to the empty sprite, which is required by commands that use sprites, like <code>GetSprite(</code> or <code>FlipSpriteC(</code>. Defining an empty sprite is useful for when you want to create a sprite from what’s already on screen (or on buffer).

== Drawing sprites ==

There are a couple commands available in ICE that are used to display sprites, but for these examples, we will stick to the standard command, <code>Sprite_NoClip(</code> (<code>det(59</code> in the program editor). The syntax for <code>Sprite_NoClip(</code> is:<br />


<code>det(59,PTR,X,Y)</code>


<code>PTR</code> should be the pointer that was returned from <code>DefineSprite(</code> returns (see the previous section), in our case the variable <code>A</code>. <code>X</code> and <code>Y</code> are the coordinates where ICE will put the sprite.<br />
Here is an example program to draw a mini apple sprite to the screen:<br />


<code>[i]OUTPUT DefineSprite(4,4,"FF25E8FFE8E8E0E8E8E000E0FFE8E0FF")-&gt;A det(0 det(59,A,20,50 Pause det(1 </code>


Once you compile and run that program, you’ll get a blank screen with a small apple near the top left corner. Hit enter to exit the program.<br />
Notice how the example program uses <code>det(0</code> and <code>det(1</code>. This is because <code>det(0</code> is used to set up the graphics canvas to allow for the use of any of the graphics functions, and then <code>det(1</code> closes the graphics canvas and sets it up for TI-OS, which is what you want to do when your program ends, because it returns to TI-OS.<br />
As you can see, drawing sprites is relatively easy and only requires a bit of effort when making and converting the sprites themselves.<br />
You can have up to about 64K bytes worth of sprites in your ICE program, so it’s likely you won’t need to worry about using too many sprites. Just remember that they do take space in your program.<br />
As for the other sprite commands available in ICE, they work quite similarly and are covered in more detail later. The similar command <code>Sprite</code> draws a ''clipped'' sprite to the screen, using the same syntax as <code>Sprite_NoClip</code>.<br />
If you want to display a transparent sprite, add the following line to the <code>convpng.ini</code> file:<br />


<code>#TransparentColor : &lt;red&gt;, &lt;green&gt;, &lt;blue&gt;, (&lt;alpha&gt;)</code>

Where &lt;red&gt;, &lt;green&gt;, &lt;blue&gt;, and &lt;alpha&gt; are the RGBA values of a the color that will be treated as transparent. Then display the sprite with one of the transparent sprite commands, such as <code>TransparentSprite(</code> or <code>TransparentSprite_NoClip(</code> (they both use the same exact syntax as the <code>Sprite_NoClip(</code> command we just covered, but they are used for sprites with transparency instead).


= Tilemaps =

Games often use tilemaps, so it’s important to cover them in this guide. Using tilemaps is a bit harder than sprites, but definitely not impossible. You need [https://github.com/mateoconlechuga/convpng/releases/latest ConvpNG] and [https://github.com/mateoconlechuga/convpng/release/latest ConvTile] to convert to ICE format. Be sure to put them both in the same folder! To edit tilemaps, we will use [http://www.mapeditor.org/ Tiled].

== Create tilemaps ==

You can’t use tilemaps without a tileset. This means we first need to make a tileset, consisting of tiles of equal size. Again, you can use your favorite sprite editor (tiles are basically sprites). Be sure to save the tileset as a .PNG in the same folder as the three tools! In this guide we will use this tileset:

[[File:tileset.png|image]]

With this tileset we are going to create the tilemap. That is why we need Tiled, a 2D level editor that will help us designing the tilemap. When you open Tiled, you need to create a tilemap, so click on the button New Map.<br />


{|
|

| '''Note: Tile layer format should be CSV!'''
|}

Change the map size and tile size to what you want, and save it in the folder where you stored the tools and tileset. But, we currently have only an empty tilemap, without any tiles. Click on File &gt; New &gt; New Tileset, browse for your tileset and save this tileset somewhere (you don’t need it, unless you want to create more tilemaps with the same tileset). Go back to your tilemap, and start editing! Example:<br />


[[File:tilemap2.png|image]]<br />


When you are ready with editing, export this tilemap as a '''.csv''' file, and be sure to save it in the same folder again. Now we need to convert the <code>.csv</code> file to ICE format, and what is why we need <code>ConvTile</code>. Open Command Prompt, navigate to the folder, and run <code>convtile --ice</code>. The converted files will be in <code>tilemaps.txt</code>.

However, we still have one big problem. A tileset of 128x64 doesn’t fit within one program! The only solution would be to store it in an appvar, and load the tileset from the appvar in ICE. That is why we need to use ConvPNG again. Create a new file with the following text in it:

<pre>#AppvarICE          : TILES
#PNGImages          :

#GroupICE           : tileset_gfx
#OutputPaletteArray : false
#Tilemap            : 16,16,true
#Palette            : xlibc
#PNGImages          :</pre>
Put the name of the tileset under both the <code>#PNGImages :</code> lines, and save the file as <code>convpng.ini</code>, again in the same folder. Double-click on the <code>convpng.exe</code> file, and if everything went right, TILES.8xv will be created, and <code>tiles.txt</code>. You will see a line of text which looks like this:<br />


<code>"TILES",0,384</code>

These are the arguments of <code>LoadData(</code>, which we will explain in the next section.

== Load tilemaps ==

As said in the previous section, the tileset is stored in an appvar, so be sure to transfer <code>TILES.8xp</code> to your calculator. We need to ’load’ the appvar data in our ICE program, and that is what the token <code>LoadData(</code> is for. Copy the data from the text file and put the token in front of it. This returns a pointer to the '''table with pointers to the sprites'''. If you have no idea what that means; no problem, you don’t need to understand it. However, you need to store this pointer into a variable, which we will use in <code>DefineTilemap(</code>. The syntax for <code>DefineTilemap(</code> is this:<br />


<code>DefineTilemap(TILE_HEIGHT,TILE_WIDTH,DRAW_HEIGHT,DRAW_WIDTH,</code>

<code>TYPE_WIDTH,TYPE_HEIGHTTILEMAP_HEIGHT,TILEMAP_WIDTH,Y,X,PTR[,"MAP_DATA"])</code>

The most important argument is the <code>PTR</code> one; that '''must''' be the variable holding the pointer from <code>LoadData(</code>. Something else doesn’t work! The other arguments should be straightforward, and they should all be numbers. You can get the <code>"MAP_DATA"</code> from <code>tilemaps.txt</code>, which we already converted earlier. This function returns a pointer to the tilemap struct, which should be used in the tilemap functions.

== Display tilemaps ==

Displaying tilemaps is as easy as display sprites! There are a few tilemap functions, and we will use one: <code>Tilemap_NoClip(</code>. The first argument should be the pointer returning from <code>DefineTilemap(</code>. The two other arguments are the coordinates where the tilemap should be displayed. If you don’t understand this section, feel free to look at the code of the sample program, later in this guide.

== Change tilemaps ==

If you have a game with multiple levels with the same tileset, you can easily change the tilemap struct such that it points to some different map data. To change it, just do this:<br />


<code>"MAP_DATA"->{PTR}</code>

This loads a pointer to the new map data in the sprite struct. <code>PTR</code> should be the pointer returning from <code>DefineTilemap(</code>. Nothing changes of the tilemap commands, you can just use the same variable.


= Code Snippets =

== randInt( ==

ICE doesn’t support the TI-BASIC token <code>randInt(</code>. We need a small trick to simulate it. You need to notice that <code>randInt(1,6)</code> is basically the same as <code>1+remainder(rand,6-1+1)</code>.<br />
<code>remainder(rand,6)</code> returns a number in between 0 and 5, and adding 1 gives us a random number in the range <code>[1,6]</code>, which is what we needed. To make it more general:<br />


<code>randInt(A,B)=A+remainder(rand,B-A+1)</code>

You’ll need this code snippet routine a bunch of times in your program, so it might be useful to remember it.

== Double buffering ==

The 84+CE is capable of having a screen buffer ''and'' another buffer, which is perfect for games. You can display one buffer, while drawing to the other buffer, which isn’t visible. At the end of the loop, you can then just swap the LCD pointers with <code>SwapDraw(</code> to display the back buffer, and set the current visible buffer to the back buffer. It’s very easy to use:

<pre>Begin
SetDraw(1)
While ...
...
SwapDraw
End</pre>
You need to tell your program to draw always at the back buffer with <code>SetDraw(1)</code>. Then your main loop starts. At the end of the main loop, you swap the pointers with <code>SwapDraw</code>. Then your program loops again, drawing to the back buffer, and displaying that buffer at the end of the loop. This has the main advantage that you don’t see the screen objects being drawn. Instead, it displays all the objects at the same time!

== Listing Variables ==

Sometimes you want to list all the available files on calc, and often that are programs, for example when you create a shell or IDE. This is pretty easy with ICE, but you need to know it, so let’s see what the possibilities are. We already have <code>DetectVar(</code> and <code>Detect(</code>, so let’s use them. The documentation says the first argument is <code>POS</code> where it should be 0 if the want to find the first variable. Let’s use this to create a small code snippet to find all the available programs, and open them!<br />
<br />


<pre>0->POS
While DetectVar(^^oPOS,0,5)->PROG
//^^o is the degree symbol, [2nd][apps][1]
OpenVar(PROG,"r",5)->SLOT
...
End</pre>
You can use <code>DetectVar(</code> recursively, because <code>POS</code> gets automatically updated to find the next program.<br />


{|
|

| '''Note: The programs are found as how they are stored in the VAT, not alphabetically!'''
|}

= Sample Game =

We’ve made an example game for you: ''The World Hardest Game''. You can grab it from SourceCoder3 [http://sc.cemetech.net/?hash=4zg9HFHQTJGb2FRzQFxn6OZa9Zcb here]. In this documentation guide we don’t explain how everything works, that takes too much space and time. The program itself has a lot of comments, and with these comments you should be able to understand it. If not, feel free to ask at [https://www.cemetech.net/forum/viewforum.php?f=90 ] or send a message to PT_, see the next section.

= Questions &amp; contact =

If you still have questions about anything ICE-related, feel free to post it in the right [https://www.cemetech.net/forum/viewforum.php?f=90 topic] at Cemetech. You can also send a personal message to PT_ [https://www.cemetech.net/forum/privmsg.php?mode=post&u=PT_ here] or send him an email:<br />
[mailto:petertillema@solcon.nl send]. You can also find information and tips and tricks at [http://ice.cemetech.net Cemetech].


-----

''Message from PT_: thanks everyone for helping, testing and giving feedback! I highly appreciate it, and I enjoy seeing new programs appearing in the ICE language. Credits to KryptonicDragon who helped me a lot finding bugs and writing this documentation. Also thanks to MateoConLechuga for helping with defining ICE syntax and for modifying his very useful tools to output ICE format. Cheers!''


-----