Assembler - Macros
These macros are supported:
- !TO
- !SOURCE
- !BINARY, !BIN, !BI
- !BYTE, !BY, !8, !08
- !WORD, !WO, !16
- !FILL, !FI
- !TEXT, !TX, !SCR
- !CONVTAB, !CT
- !PSEUDOPC
- !REALPC
- !BANK
- !ZONE, !ZN
- !ERROR
- !IFDEF, !IF
- !IFNDEF
!TO [file name],[output type]
This macro includes overrides any build target settings given in the element properties. The output file name and type of the current file are determined.
Valid output types are CBM, PLAIN, CART8BIN, CART8CRT, CART16BIN, CART16CRT, MAGICDESKBIN, MAGICDESKCRT, D64, T64
For cartridge and tape/disk formats a dummy name is currently inserted in the final file.
!to "jmain.prg",cbm
!to "cart64banks.crt.bin", magicdeskcrt
!SOURCE [file name]
This macro includes another source file at the current location.
!source "tiles.asm"
!BINARY, !BIN, !BI [file name]<,[size]>,<[skip]>"
This macro inserts a file as binary data.
<size> sets the number of bytes that are read from the file. If it is not set the whole file is included.
<skip> sets the number of bytes that are skipped from the start of the file. If it is not set no bytes are skipped.
!bin "soulless20.bin"
!binary "music.prg",,2
!BYTE, !BY, !8, !08
This macro allows to insert one ore more bytes at the current location.
Allowed are constant values, expressions and labels as content.
Constant values can be set as decimal, hexadecimal (with prefixed $), chars (surrounded by ' or ").
Labels are treated as 16-bit values. To get the high or low byte prefix the label with $lt; (low byte) or $gt; (high byte)
Expressions are evaluated during the final pass. They must evaluate to a valid byte value.
!byte 1,3,6,3,1
!byte <NoBehaviour
!byte ( SCREEN_CHAR + 0 ) & 0x00ff
!WORD, !WO, !16
This macro allows to insert words (2 bytes) at the current location.
Allowed are constant values, expressions and labels as content.
Constant values can be set as decimal, hexadecimal (with prefixed $).
Labels are treated as 16-bit values.
Expressions are evaluated during the final pass. They must evaluate to a valid word value.
!word 128,270,320
!word NoBehaviour
!word ( SCREEN_CHAR + 40 )
!FILL, !FI [count],[value]
This macro fills the given value count times at the current location.
!fill 8,$ff
!fill ITEM_COUNT,0
!TEXT, !TX, !SCR
This macro allows to insert text, characters, or one ore more bytes at the current location.
Allowed are text literals, character literals, constant values, expressions and labels as content.
text literals are surrounded by ", character literals by '
Constant values can be set as decimal, hexadecimal (with prefixed $), chars (surrounded by ' or ").
Labels are treated as 16-bit values. To get the high or low byte prefix the label with $lt; (low byte) or $gt; (high byte)
Expressions are evaluated during the final pass. They must evaluate to a valid byte value.
Any values are subject to being mapped to the current set conversation table.
!text "HELLO WORLD"
!text " SCORE",60," 00000000 ",224,224," LEVEL",60," 00 ",225,225," LIVES",60," 03 *"
!text 206,184,191,182,198,196,184,0,203,198,0,202,198,204,191,191,184,202,202,0,0
!CONVTAB, !CT [raw/scr]
This macro allows sets a conversion table for text in !TEXT entries. Currently only the values
raw or
scr are supported.
If RAW is set byte values are inserted as is.
If SCR is set any byte values are mapped to screen codes.
!CONVTAB scr
!text "HELLO WORLD"
!PSEUDOPC [address]
This macro alters the following assembly as if the current memory location was starting with the provided address.
Allowed are constant values, expressions and labels as content. Mainly useful for code that will be copied around or bank switched (cartridge).
When setting !REALPC the program counter is set to the proper location address again.
!PSEUDOPC $0400
...
!REALPC
!REALPC
This macro is the counter part for !PSEUDOPC. The following assembly is used the proper memory location.
When setting !REALPC the program counter is set to the proper location address again after a !PSEUDOPC.
!PSEUDOPC $0400
...
!REALPC
!BANK [bank index],[bank size]
This macro is for the support of cartridge banks. Any following assembled code is filled to the given bank size when the end of file or another !BANK macro is encountered.
Usually !BANK will be used in conjunction with a !PSEUDOPC.
!bank 0,$2000
!ZONE [zone name]
This macro declares a new zone. Any local labels (labels starting with '.') are only accessible inside their containing zone.
!zone MainZone
.locallabel
...
!zone SubZone
.locallabel
!ERROR [message]
This macro adds an error message to the output, essentially breaking the build.
This macro can be useful inside conditional macro statements to do safety checking.
!error File too long
!IF, !IFDEF [expression] {
This macro starts an conditional block. The conditional block is only evaluated if the expression yields a result not equal to zero. The opening curly brace must be on the same line.
A conditional block has to end with a closing curly brace. An optional else statement may open an opposite conditional block, however it must be stated on one line.
!ifdef MUSIC_PLAYING{
;initialise music player
ldx #0
ldy #0
lda #MUSIC_TITLE_TUNE
jsr MUSIC_PLAYER
} else {
;start sfx engine
lda #0
jsr SFX_PLAYER
}
!IFNDEF [expression] {
This macro starts an conditional block. The conditional block is only evaluated if the expression yields a result of zero. The opening curly brace must be on the same line.
A conditional block has to end with a closing curly brace. An optional else statement may open an opposite conditional block, however it must be stated on one line.
!ifndef COMPILE_CRUNCHED {
CHARSET
!binary "soulless1.chr"
!binary "soulless2.chr"
CHARSET_PANEL
!binary "panel.chr"
SPRITES
!binary "soulless.spr"
} else {
;start sfx engine
lda #0
jsr SFX_PLAYER
}