tutor.doc

This file is intended to explain how to get started with making something
with Super ZZ Zero. You will need to install it first (you can install a
release or pre-release version (only for 64-bit x86 Linux), or you can
compile it by yourself).


=== Configuration ===

Create a file in your home directory called ".superzz0rc". Inside of this
file, you should add the configuration options. They are fully documented
in the file called config.doc, but here is a simple explanation of some of
the options which may be more common.

The below is an example which you may copy and then modify according to
your preferences. (None of these are required, but they are probably the
most common things that you might want to add.)

audio_buffer=512
audio_filter=0.75
audio_rate=44100
audio_volume=8000
help=/home/user/superzz0/help/
music_amp=0.81
music_resample=16 16 L0.89 B I
wave_resample=16 16 L0.89 B I
wave_sound=1

The "help=" line should be the full path of the directory containing the
help files. (In the releases, this is "superzz0-release/help/"; you will
have to add the full path before that, and if you renamed the directory
then you will need to change it to the new name of that directory.)


=== Creating a world using a template ===

A world can be created using an existing template or it can be created
without using a template. The easier method will probably be to use a
template, so this will be explained first.

To create a new world file, enter the command:
  superzz0 -et template/default.sz0 world1.sz0
(This assumes that you will want to call the file "world1.sz0" and that
the template is stored in the subdirectory called "template" of the current
working directory.)

Now, the main menu of the editor will be displayed. If you have configured
it correctly, then on this and most other editor menus you can push ALT+?
to display the help file for the currently displayed menu.

Select the "Boards" submenu, and then select "Add new board". You can then
enter a name for the new board, and then the board editor is displayed.

In the board editor, add the player by moving the cursor to the appropriate
position and then push F5 and then Z to add the player. (Since there is the
default colour for the player, setting the colour at first is not necessary
unless you configured it to not use the default colour. However, for walls
and other stuff, it will be necessary to set the colour.)

You can also add other stuff. For example, move cursor to somewhere and
then push c and select a colour, and then F3 S adds a solid wall. If you
push TAB and then move the cursor, it will continuously draw a wall until
you push TAB again to cancel continuous drawing mode.

You can add other stuff as well if you want to do, and push ALT+T to test
the world; after testing, push F10 to return to the editor.

You can push escape to exit this menu and push again to escape the board
list menu. On the main menu, push ALT+S to save; you should do this often
enough that it does not get lost, and must be done before you quit so that
it does not get lost.

If you go back into the board list menu again then you can see the list of
the boards that are already added, and you can select one to view and edit
that board.

Next thing that will be considered here is a scriptable object. Select the
colour (by pushing c and then selecting one of the colours), and move the
cursor to the appropriate position, and then F5 O to add a scriptable
object. Once you do this, it will ask you to pick which PC character it
will be represented by, and then the text editor is displayed.

See the file called script.doc for information about the script format,
but this file also has a simple explanation. Also note that the program
memory (which is already defined in the template) may define additional
commands and messages which may be used. (See the next section about
"creating a world without a template" if you want to change these.)

On the first line, you should write the name of the object with a at sign
in front. The other lines specify what it will do; the commands will be
executed in order. Here is an example:

@Salesman
#end
:touch
What do you want to buy?
!a;Ammunition
!b;Torch
#end
:a
#take c 1 =noitem
#give a 1
OK
#end
:b
#take c 1 =noitem
#give t 1
OK
#end
:noitem
You don't have enough.
#end

The first "#end" line prevents being executed immediately.

The ":touch" line is a message defined in the template; when the player
touches this object then it will do what is written in the next lines.
This is a multi-line text which will be displayed; the lines with "!" are
choices that the player may select and if one is selected, then the part
between "!" and ";" is the name of the label to go to. After this text
will also be "#end" to stop execution afterward.

Then, lines ":a" and ":b" are the labels you had mentioned above, that
will be used when the selection is made.

The "#take c" will deduct 1 from the status variable "C", which is used
for money in the default template. This cannot reduce it below zero; if
it is not enough then it will execute the command on the rest of the line,
which is "=noitem" to go to the ":noitem" label in case you do not have
enough money to buy that.

If you do have enough, then "#give a 1" will give you one ammunition,
and then "OK" is a single line message and then "#end" stops it.

If you want to try this, then you should also add some money into the
board (the money is in the F1 menu), so that you can buy it.


=== Creating a world without a template ===

If you want to create a world without a template, then it is more
complicated than using a template. (It is also possible to take some
of the code from a template if you want to use some similar things.)

To create a new world file without a template:
  superzz0 -ew world2.sz0

You can now define elements and other stuff. Remember that on nearly any
menu you can push ALT+? for help.

Go to the "Elements" menu. In this menu you can select a element to define
its name and attributes. The name must be filled in, if you want it to be
saved; if the name is left blank then this element will not be saved.

Element 0 is used as the default empty space, so should be a floor element
that is suitable for that. Enter the name (e.g. "EMPTY"; it will convert
your entry into uppercase automatically here), select "Floor". The other
things can be left as they are.

You can then add additional elements (you do not have to add all of them
right away; you can add some later, too). Most games will have one "player"
element, so you should add that one too, and should ensure that it is
allowed to move on whatever class you want it to move on (probably class 0,
but you can use other class numbers).

You will then have to write a .asm file; by convention this should have the
same name as the world file but with ".asm" instead of ".sz0"; for this
example, it will be called "world2.asm". This is a plain text file that you
can write using any text editor.

See asm.doc for the syntax and usage of the assembler, and opcodes.doc for
the details of the instruction opcodes, and event.doc for details about the
meaning of built-in events and of the memory cells $0080 to $00FF.

You can also look at the .asm files of the default template and of the
snake game for further examples of its working, and you may copy some of
the code if you wish (they are public domain).

You will probably want to define the keyboard event; see a below section
for a simple example, including an explanation.

When Super ZZ Zero is not running, you can run the assembler like:
  sz0asm -w world2.asm - | superzz0 -ea world2.sz0

This will then compile your program into the program memory in the world
file and will define events for the elements. You can do this again later
if changes are made to your .asm file. This does not affect anything which
is defined within the Super ZZ Zero editor.

You will also need to define at least one screen, and have the boards to
be associated with that screen. If you are using text windows, a separate
screen should be added for the text windows.

And then, you can add a board. If editor menus are not defined within the
.asm file then you cannot use the function keys to display such menus in
the board editor, although you can enter element numbers manually by the
use of the e key.

Also note that scripts do not run automatically; you must add commands to
execute them within the .asm file in order to work.


=== Keyboard event example ===

; Address of keyboard vector.
; TA will write the current assembling address to the vector.
	TA $E0
; The W register stores the key code and Z stores the direction. For this
; purpose, only the direction is relevant. The W,X,Y,Z registers are local
; registers, and they are not usable for all purposes, so it must be copied
; to the A register.
	LET A,Z
; If no direction is pushed, then Z=-1 so ignore it.
	JNEG A,0
; Move the player (the first instance of stat 1). See opcodes.doc for an
; explanation of SMOV; the value $0050 allows pushing and transporting.
	LET B,1
	SMOV B,$0050
	LET S,0