Kick Assembler

https://www.theweb.dk/KickAssembler/webhelp/
Admin
Kick Assembler is an advanced MOS 65xx assembler combined with a JavaScript-like script language,...
Tokens:59,854
Snippets:555
Trust Score:7.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Running Kick Assembler Command Line

Source: https://www.theweb.dk/KickAssembler/webhelp/content/cpt_GettingStarted

This command executes the Kick Assembler JAR file to assemble a given .asm file. Ensure Java 8.0 or higher is installed and accessible from the command line.

```shell
java –jar kickass.jar myCode.asm
```

--------------------------------

### KickAssembler: Basic Upstart Program with BasicUpstart2 Macro

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch14s02

Shows the BasicUpstart2 macro, a variation that also handles memory block setup in addition to creating the BASIC loader. The example code is identical to the BasicUpstart example in its machine code logic, incrementing colors and looping. This macro is useful for more complex memory management scenarios. Assumes the KickAssembler environment.

```assembly
BasicUpstart2(start)    // 10 sys$0810
start:  inc $d020
        inc $d021
        jmp start

```

--------------------------------

### Full Example: Segment Definitions and Usage (KickAssembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s06

A comprehensive example showcasing segment definitions (.segmentdef), file configuration (.file), and the usage of named segments for code and data. It includes routines for main execution, color setup, and text display, demonstrating how segments group related code and data.

```kickassembler
.segmentdef Code [start=$0900]
.segmentdef Data [start=$8000]
.file [name="segments.prg", segments="Code,Data", modify="BasicUpstart", marg1=$0900]

//--------------------------------------------------------
// Main
//--------------------------------------------------------
        .segment Code "Main"
        jsr colorSetup
        jsr textSetup 
        rts 

//--------------------------------------------------------
// Color
//--------------------------------------------------------
        .segment Code "Color Setup"
colorSetup:
        lda colors
        sta $d020
        lda colors+1
        sta $d021
        rts
        
        .segment Data "Colors"
colors: .byte LIGHT_GRAY, DARK_GRAY
              

//--------------------------------------------------------
// Text
//--------------------------------------------------------
        .segment Code "Text Setup"
textSetup: { 
        ldx #0
loop:   lda text,x
        cmp #$ff
        beq out
        sta $0400,x
        inx
        jmp loop
out:
        rts
        
        .segment Data "Static Text"
text:   .text "hello world!"
        .byte $ff
}
```

--------------------------------

### Checking Java Installation Version

Source: https://www.theweb.dk/KickAssembler/webhelp/content/cpt_GettingStarted

This command verifies if Java is correctly installed and accessible from the command prompt by displaying the Java version. This is a troubleshooting step for users experiencing issues with Java path configuration.

```shell
java –version
```

--------------------------------

### File List Format Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch15s04s05

This example demonstrates the 'index;filepath' format for listing files. The 'filepath' can include a JAR file prefix to denote internal resources, and paths may contain semicolons.

```plaintext
[files]
0;KickAss.jar:/include/autoinclude.asm
1;test1.asm
```

--------------------------------

### Creating a Multi-Bank Cartridge File (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s02

This example demonstrates creating a multi-bank cartridge file ('myfile.bin') using Kick Assembler segments. It defines four bank segments (BANK1 to BANK4), each restricted to the address space $1000-$1fff, and outputs them in order to a binary file.

```kickassembler
.segment CARTRIDGE_FILE [outBin="myfile.bin"]
    .segmentout [segments ="BANK1"]
    .segmentout [segments ="BANK2"]
    .segmentout [segments ="BANK3"]
    .segmentout [segments ="BANK4"]

.segmentdef BANK1 [min=$1000, max=$1fff, fill]
.segmentdef BANK2 [min=$1000, max=$1fff, fill]
.segmentdef BANK3 [min=$1000, max=$1fff, fill]
.segmentdef BANK4 [min=$1000, max=$1fff, fill]

.segment BANK1
..code for segment 1 goes here...

.segment BANK2
..code for segment 2 goes here...

.segment BANK3
..code for segment 3 goes here...

.segment BANK4
..code for segment 4 goes here...
```

--------------------------------

### Outputting Code to a Segmented File (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s02

This example shows how to define a segment named 'File1' and direct its output to a program file named 'MyFile.prg'. It demonstrates basic segment definition and output redirection.

```kickassembler
.segment File1 [outPrg="MyFile.prg"]
    *=$1000
    lda #00
    ... more code ...
.segment Default
```

--------------------------------

### Example Assemble Info File Content

Source: https://www.theweb.dk/KickAssembler/webhelp/content/cpt_AsmInfo

This snippet shows an example of the content found in an 'asminfo.txt' file, illustrating the different sections like libraries, directives, files, syntax, and errors.

```text
[libraries]
Math;constant;PI
Math;constant;E
Math;function;abs;1
Math;function;acos;1
...
[directives]
.text;.text "hello";Dumps text bytes to memory.
.by;.by $01,$02,$03;An alias for '.byte'.
...
[files]
0;KickAss.jar:/include/autoinclude.asm
1;mySource.asm
[syntax]
symbolReference;38,8,38,17,0
symbolReference;41,20,41,26,0
functionCall;41,8,41,18,0
symbolReference;56,8,56,17,0
...
[errors]
...
```

--------------------------------

### KickAssembler: Basic Upstart Program with BasicUpstart Macro

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch14s02

Demonstrates the use of the BasicUpstart macro to create a simple BASIC loader for machine code. This macro automatically generates a BASIC line to 'SYS' to the specified program start address. The example code increments the border and background colors and then jumps back to itself. Assumes the KickAssembler environment.

```assembly
        *= $0801 "Basic Upstart"
        BasicUpstart(start)    // 10 sys$0810

        *= $0810 "Program"
start:  inc $d020
        inc $d021
        jmp start

```

--------------------------------

### Example Memory Blocks in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s04s04

This code snippet demonstrates the definition of two memory blocks in KickAssembler. Each block is assigned a starting address and contains either raw byte data or assembly instructions.

```kickassembler
*=$1000 "Block 1"
.byte 1,2,3

*=$2000 "Block 2"
lda #1
sta $d020
rts
```

--------------------------------

### Hashtable Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Demonstrates the Hashtable value type, used for key-value pair storage. Example shows instantiation.

```KickAssembler
Hashtable()
```

--------------------------------

### Kick Assembler: Interrupt and Music Playback Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch02s02

This Kick Assembler code demonstrates setting up a non-maskable interrupt (IRQ) to play music and control the border color. It utilizes macros for setting the border color and includes an external binary file for the music data. The program initializes music playback, configures the IRQ vector, and enters an infinite loop while the interrupt handles music and visual updates.

```assembly
BasicUpstart2(start)
//----------------------------------------------------------
//----------------------------------------------------------
//   Simple IRQ
//----------------------------------------------------------
//----------------------------------------------------------
        * = $4000 “Main Program”
start:  lda #$00
        sta $d020
        sta $d021
        lda #$00
        jsr $1000    // init music
        sei
        lda #<irq1
        sta $0314
        lda #>irq1
        sta $0315
        lda #$7f
        sta $dc0d
        sta $dd0d
        lda #$81
        sta $d01a
        lda #$1b
        sta $d011
        lda #$80
        sta $d012
        lda $dc0d
        lda $dd0d
        asl $d019
        cli
        jmp *

//----------------------------------------------------------
irq1:   asl $d019
        SetBorderColor(2)
        jsr $1003    // play music
        SetBorderColor(0)
        jmp $ea81

//----------------------------------------------------------
        *=$1000 “Music”
        .import binary “ode to 64.bin”

//----------------------------------------------------------
// A little macro
.macro SetBorderColor(color) {
        lda #color
        sta $d020
}

```

--------------------------------

### BasicUpstart Segment Modifier Example (KickAssembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s13

This code snippet demonstrates the use of the 'BasicUpstart' segment modifier in KickAssembler. It defines a file and a code segment, specifying 'BasicUpstart' as a modifier to add a BASIC upstart program that jumps to the provided start address ($8000 in this case).

```kickassembler
.file [name="test.prg", segments="Code"]
.segment Code [start=$8000, modify="BasicUpstart", _start=$8000]
inc $d020
jmp *-3

```

--------------------------------

### List Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Illustrates the List value type, representing an ordered collection of items. Example shows instantiation.

```KickAssembler
List()
```

--------------------------------

### KickAssembler: Create and Manipulate List with Set and Get

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch06s02

Demonstrates how to create a list with a specified size and then set and retrieve elements at specific indices. The get operation retrieves the element, which can be a number or a string.

```kickassembler
.var myList = List(2)
.eval myList.set(0,25)
.eval myList.set(1, "Hello world")
.byte myList.get(0)    // Will give .byte 25
.text myList.get(1)    // Will give .text "Hello world"
```

--------------------------------

### KickAssembler: Create and Add Elements to a List, Get Size

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch06s02

Shows how to create an empty list and then add multiple elements to it using the add() function. It also demonstrates how to get the current number of elements in the list using the size() function.

```kickassembler
.var greetingsList = List()
.eval greetingsList.add("Fairlight", "Booze Design", "etc." )
.byte listSize = greetingsList.size()    // gives .byte 3
```

--------------------------------

### Parameter Map Definition Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s04s05

This shows the typical syntax for defining source code parameters within square brackets, specifying name-value pairs.

```text
[name="Kevin", age=27, hacker=true]
```

--------------------------------

### Struct Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Illustrates the Struct value type, which represents user-defined structures. Example shows instantiation with parameters.

```KickAssembler
MyStruct(1,2)
```

--------------------------------

### Java 'Hello World' Macro Implementation

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s03

A concrete implementation of a Kick Assembler macro plugin named 'MyMacro'. It prints 'Hello world from mymacro!' to the engine and returns an empty byte array.

```java
package test.plugins.macros;
import kickass.plugins.interf.general.IEngine;
import kickass.plugins.interf.general.IValue;
import kickass.plugins.interf.macro.IMacro;
import kickass.plugins.interf.macro.MacroDefinition;

public class MyMacro implements IMacro {
   MacroDefinition definition;
   
   public MyMacro() {
      definition = new MacroDefinition();
      definition.setName("MyMacro");
   }

   @Override
   public MacroDefinition getDefinition() {
      return definition;
   }

   @Override
   public byte[] execute(IValue[] parameters, IEngine engine) {
      engine.print("Hello world from mymacro!");
      return new byte[0];
   }
}
```

--------------------------------

### Kick Assembler Macro Execution Syntax

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s03

Shows the syntax for executing the 'MyMacro' plugin within the Kick Assembler environment. It involves specifying the plugin path and calling the macro.

```assembly
.plugin "test.plugins.macros.MyMacro"
MyMacro()

```

--------------------------------

### Argument Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Demonstrates the Argument value type, used to define arguments passed to mnemonics. Example shows syntax with optional index.

```KickAssembler
($10),y
```

--------------------------------

### OutputFile Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Illustrates the OutputFile value type, used for creating output files. The createFile function is used to instantiate this type.

```KickAssembler
createFile("breakpoints.txt")
```

--------------------------------

### Vector Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Shows the Vector value type, representing a 3D vector. Example demonstrates instantiation with three coordinates.

```KickAssembler
Vector(1,2,3)
```

--------------------------------

### KickAssembler: Define Code and Data segments with example content

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch11s03

Demonstrates the definition of 'Code' and 'Data' segments. The 'Code' segment contains basic assembly instructions, while the 'Data' segment initializes memory blocks with calculated values.

```assembly
// Define some segments 
.segment Code []
BasicUpstart2(start)
start:
        inc $d020
        jmp *-3

        .segment Data []
        *=$0f00 "Mul3"
        .fill $40, i*3        

        *=$2000 "Sinus"
        .fill $100, 127.5 + 127.5*sin(toRadians(i*360/256))
```

--------------------------------

### Kick Assembler Boolean Operator Examples

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch08s05

Demonstrates the usage of boolean operators like !, &&, ||, ==, and parentheses within Kick Assembler's #if and #importif preprocessor directives. These examples show how to conditionally include code or import files based on symbol evaluation.

```kickassembler
#if !DEBUG && !COMPLICATED
   // some stuff 
#endif

#if DEBUG || (X && Y && Z) || X==DEBUG
   // Note that you can also use parenthesis#

#importif DEBUG&&STANDALONE "UpstartWithDebug.asm"
```

--------------------------------

### Plugin Interface

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s05

This describes the general interface for plugins. Most plugins have two methods: one to get the plugin's definition and another to execute it.

```APIDOC
## Plugin Interface

### Description
This is the general interface that all plugins extend. It typically includes methods for retrieving the plugin's definition and for executing its functionality.

### Method
```java
interface XYZPlugin extends IPlugin {
   XYZDefinition getDefinition();
   void execute(...);
}
```

### Request Example
```json
{
  "example": "Not applicable for interface definition"
}
```

### Response
#### Success Response (200)
- **XYZDefinition** (object) - An object containing the plugin's definition details.

#### Response Example
```json
{
  "example": "Not applicable for interface definition"
}
```
```

--------------------------------

### SidFile Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Demonstrates the SidFile value type, used for loading SID music files. The LoadSid function is employed here.

```KickAssembler
LoadSid("music.sid")
```

--------------------------------

### Using Label Directive for Cleaner Scope Access (KickAssembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch09s06

This example shows how to use the '.label' directive to define a label within a scope, simplifying access to it. It achieves the same screen-filling functionality as the previous example but avoids the need to manually adjust addresses when accessing labels like 'fillbyte'.

```assembly
        lda #’a’
        sta clearScreen2.fillbyte
        jsr clearScreen2
        rts

ClearScreen2: {
        .label fillbyte = *+1
        lda #0
        ldx #0
loop:
        sta $0400,x
        sta $0500,x
        sta $0600,x
        sta $0700,x
        inx
        bne loop
        rts
}
```

--------------------------------

### Number Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Illustrates the Number value type, representing floating-point numbers.

```KickAssembler
27.4
```

--------------------------------

### Macro Plugin Interface

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s05

Defines the interface for Macro Plugins, including methods to get the MacroDefinition and execute the macro with parameters.

```APIDOC
## Macro Plugin Interface

### Description
This interface defines the contract for Macro Plugins. It includes a method to retrieve the `MacroDefinition` and an `execute` method that takes an array of `IValue` parameters and an `IEngine`.

### Method
```java
public interface IMacro extends IPlugin {
   MacroDefinition getDefinition();
   byte[] execute(IValue[] parameters, IEngine engine);
}

public class MacroDefinition {
   private String name;
   // Getters/setters for properties, in this case getName() and setName(name)
   // ...
}
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **parameters** (IValue[]) - An array of values representing the parameters for the macro execution.
- **engine** (IEngine) - The engine instance to be used during execution.

### Request Example
```json
{
  "parameters": [
    // ... IValue objects ...
  ],
  "engine": "// ... IEngine object ..."
}
```

### Response
#### Success Response (200)
- **byte[]** - The result of the macro execution as a byte array.

#### Response Example
```json
{
  "example": "[byte array representing execution result]"
}
```
```

--------------------------------

### General Plugin Interface Definition

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s05

Defines the basic structure for a plugin, requiring methods to get its definition and execute its functionality. The definition class allows for extensibility.

```java
interface XYZPlugin extends IPlugin {
   XYZDefinition getDefinition();
   void execute(...);
}

class XYZDefinition {
   // Properties
   private String name;

   // Getters/setters for properties, in this case getName() and setName(name)
   // ...
}
```

--------------------------------

### Get All Assemble Info with Kick Assembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/cpt_AsmInfo

This command exports all available information from Kick Assembler, including predefined and source-specific details. The output is typically written to 'asminfo.txt'.

```bash
java -jar KickAss.jar mysource.asm -asminfo all
```

--------------------------------

### Print Binary File Format Constant

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s02

Shows how to print the value or representation of a built-in binary file format constant (BF_KOALA in this example) to the console during assembly. This is useful for understanding the structure or details of the format.

```kickassembler
.print "Koala format="+BF_KOALA
```

--------------------------------

### Java MacroDefinition Class Structure

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s03

Illustrates the minimal structure for the MacroDefinition class, which primarily holds the name of the macro. Getters and setters are expected for its properties.

```java
public class MacroDefinition {
   // Properties
   private String name;

   // Getters/setters for properties, in this case getName() and setName(name)
   ....
}
```

--------------------------------

### KickAssembler .for Directive: Omitting Expressions and Step-by-Step Summation

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch05s04

Illustrates how to use the .for directive when initialization or iteration expressions are omitted. It provides examples for printing numbers and calculating a running sum, demonstrating the flexibility of the directive.

```kickassembler
.var i=0
.for (;i<10;) {
    .print i
    .eval i++
}

.for(var i=0, var sum=0;i<10;sum=sum+i,i++)  
    .print “The sum at step “ + I “ is “ + sum
```

--------------------------------

### General String Conversion in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch04s06

Demonstrates the general .string() function in KickAssembler, which can convert arbitrary values to their string representation. The example shows accessing a character within the converted string.

```kickassembler
.print 1234.string().charAt(2)    // Prints 3
```

--------------------------------

### Kick Assembler Math Library Examples

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch04s08

Demonstrates the usage of the Kick Assembler math library for generating a random number and creating a sine curve. It utilizes functions like 'random', 'round', 'sin', and 'toRadians'.

```assembly
        // Load a with a random number
        lda #random()*256

        // Generate a sine curve
        .fill 256,round(127.5+127.5*sin(toRadians(i*360/256)))

```

--------------------------------

### Kick Assembler: .number() Function Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch04s04

Shows how to use the general .number() function in Kick Assembler to get the numeric representation of an arbitrary value. This is useful for debugging or dynamic value conversion.

```assembler
.print ‘x’.number()

```

--------------------------------

### SID Player and Metadata Extraction - Kick Assembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s03

An example of a complete SID player created with Kick Assembler. It utilizes the imported SID file's properties (init, play, song data) and demonstrates how to print detailed music information during assembly.

```kickassembler
//---------------------------------------------------------
//---------------------------------------------------------
//                     SID Player
//---------------------------------------------------------
//---------------------------------------------------------
        .var music = LoadSid("Nightshift.sid")
        BasicUpstart2(start)
start:
        lda #$00
        sta $d020
        sta $d021
        ldx #0
        ldy #0
        lda #music.startSong-1
        jsr music.init
        sei
        lda #<irq1
        sta $0314
        lda #>irq1
        sta $0315
        asl $d019
        lda #$7b
        sta $dc0d
        lda #$81
        sta $d01a
        lda #$1b
        sta $d011
        lda #$80
        sta $d012
        cli
        jmp *
//---------------------------------------------------------
irq1:
        asl $d019
        inc $d020
        jsr music.play 
        dec $d020
        pla
        tay
        pla
        tax
        pla
        rti
//---------------------------------------------------------
        *=music.location "Music"
        .fill music.size, music.getData(i)

//----------------------------------------------------------
// Print the music info while assembling
.print ""
.print "SID Data"
.print "--------"
.print "location="+toHexString(music.location)
.print "init="+toHexString(music.init)
.print "play="+toHexString(music.play)
.print "songs="+music.songs
.print "startSong="+music.startSong
.print "size="+toHexString(music.size)
.print "name="+music.name
.print "author="+music.author
.print "copyright="+music.copyright

.print ""
.print "Additional tech data"
.print "--------------------"
.print "header="+music.header
.print "header version="+music.version
.print "flags="+toBinaryString(music.flags)
.print "speed="+toBinaryString(music.speed)
.print "startpage="+music.startpage
.print "pagelength="+music.pagelength

```

--------------------------------

### Define Enumerations with .enum

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch04s02

Defines a series of constants using the .enum statement. Values can be assigned implicitly (starting from 0) or explicitly. For example, `.enum {singleColor, multiColor}` defines `singleColor=0` and `multiColor=1`.

```kickassembler
.enum {singleColor, multiColor}      // Defines singleColor=0, multiColor=1
.enum {effect1=1,effect2=2,end=$ff}  // Assigns values explicitly 
.enum {up,down,left,right, none=$ff} // You can mix implicit and explicit 
                                     // assignment of values
```

--------------------------------

### Apply Block Modifier in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/cpt_Modifiers

This directive applies a modifier to a specific block of assembled code. It allows setting a starting address and defining code within the block. The 'MyModifier' is called without parameters in this example.

```kickassembler
.modify MyModifier() {
    *=$8080
main:
    inc $d020
    dec $d021
    jmp main

    *=$1000
    .fill $100, i
}
```

--------------------------------

### Kick Assembler Hashtable Definition and Usage

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch06s04

Demonstrates how to define a hashtable, add key-value pairs using put(), retrieve values using get(), and list all keys using keys(). It also shows brief initialization methods and explains how values are used as keys.

```Kick Assembler
.define ht {
    // Define the table
    .var ht = Hashtable()

    // Enter some values (put(key,value))
    .eval ht.put("ram", 64)
    .eval ht.put("bits", 8)
    .eval ht.put(1, "Hello")
    .eval ht.put(2, "World")
    .eval ht.put("directions", List().add("Up","Down","Left","Right"))

    // Brief ways of initialising tables
    .var ht2 = Hashtable().put(1, "Yes").put(2, "No")
    .var ht4 = Hashtable().put(1,"a", 2,"b", 3,"c")
}

// Retrieve the values
.print ht.get(1)    // Prints Hello
.print ht.get(2)    // Prints World
.print "ram = " + ht.get("ram") + "kb"    // Prints ram=64kb

// Print all the keys
.var keys = ht.keys()
.for (var i=0; i<keys.size(); i++) {
    .print keys.get(i)    // Prints "ram", "bits", 1, 2, directions
}

```

--------------------------------

### Assemble with Memory Map Display (Command Line)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch02s03

This command demonstrates how to assemble a program and display a memory map using the -showmem option. It requires Java and the kickass.jar executable.

```bash
java –jar kickass.jar –showmem myCode.asm
```

--------------------------------

### Kick Assembler Segment Definition and Usage Examples

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s03

Shows how to define segments using '.segmentdef' and switch between them using '.segment' in Kick Assembler. Segments can have default memory block starting addresses defined during definition. Code can be added to different segments, and you can switch back to previously used segments.

```assembly
        // Define two segments
        .segmentdef MySegment1
        .segmentdef MySegment2 [start=$1000]

        // Add code to segment1 
        .segment MySegment1
        *=$4000
        ldx #30
 l1:    inc $d021 
        dex
        bne l1

        // Add code to segment2 (Using default block starting in $1000)
        .segment MySegment2
        inc $d021
        jmp *-3

        // Switch back to segment1 and add more code.
        .segment MySegment1
        inc $d020
        jmp *-3
```

--------------------------------

### Load C64 Koala Paint Picture File

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s02

Loads a Koala Paint picture file using the 'C64FILE' template tag, which automatically handles skipping the first two bytes (start address). It then demonstrates setting up screen and color RAM based on the loaded data and displays the background color.

```kickassembler
.const KOALA_TEMPLATE = "C64FILE, Bitmap=$0000, ScreenRam=$1f40, ColorRam=$2328, BackgroundColor = $2710"
.var picture = LoadBinary("picture.prg", KOALA_TEMPLATE)

        *=$0801 "Basic Program"
        BasicUpstart($0810)

        *=$0810 "Program"
        lda #$38
        sta $d018
        lda #$d8
        sta $d016
        lda #$3b
        sta $d011
        lda #0
        sta $d020
        lda #picture.getBackgroundColor()
        sta $d021
        ldx #0
!loop:
        .for (var i=0; i<4; i++) {
           lda colorRam+i*$100,x
           sta $d800+i*$100,x
        }
        inx
        bne !loop-
        jmp *

*=$0c00;            .fill picture.getScreenRamSize(), picture.getScreenRam(i)
*=$1c00; colorRam:  .fill picture.getColorRamSize(), picture.getColorRam(i)
*=$2000;            .fill picture.getBitmapSize(), picture.getBitmap(i)
```

--------------------------------

### KickAssembler: Compact List Creation and Element Addition

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch06s02

Presents a concise syntax for creating a list and immediately populating it with elements in a single line using the List() and add() functions.

```kickassembler
.var greetingsList = List().add("Fairlight", "Booze Design", "etc.")
```

--------------------------------

### Configure KickAssembler with Persistent Options (KickAss.cfg)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch02s03

This configuration file sets persistent command line options for Kick Assembler. It enables the -showmem option to display a memory map after assembly and configures the -execute option to launch the VICE emulator.

```config
-showmem
-execute "c:/c64/winvice/x64.exe –confirmexit"
# This is a comment

```

--------------------------------

### Patching a File with Segments (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s02

Illustrates how to patch an existing file using Kick Assembler segments. A 'Base' segment loads the original file, and a 'Patch' segment contains modifications that overwrite the base. The result is written to 'Out.prg'.

```kickassembler
.file [name="Out.prg", segments="Base,Patch", allowOverlap]
.segment Base [prgFiles="basefile.prg"]
.segment Patch [] 

    *=$8021 "Insert jump" 
    jmp $8044
```

--------------------------------

### Import Binary Data from Files (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch03s09

Demonstrates importing binary data from external files using the .import directive in Kick Assembler. Supports importing raw bytes, C64 format (skipping address bytes), and text files (converting bytes to characters).

```kickassembler
// import the bytes from the file 'music.bin'
.import binary "Music.bin"

// Import the bytes from the c64 file 'charset.c64'
// (Same as binary but skips the first two address bytes) 
.import c64 "charset.c64"

// Import the chars from the text file
// (Converts the bytes as a .text directive would do)
.import text "scroll.txt"
```

--------------------------------

### Macro Scope and Non-Interference Example (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch07s02

Illustrates how macros in Kick Assembler are encapsulated within their own scope, preventing internal labels and variables from interfering with each other across different calls. This example shows two calls to 'ClearScreen' with different arguments, highlighting the non-interference.

```kickassembler
// Execute macro
ClearScreen($0400,$20)   // Since they are encapsulated in a scope 
ClearScreen($4400,$20)   // the two resulting loop labels don’t
                          // interfere


// Define macro
.macro ClearScreen(screen,clearByte) {
    lda #clearByte
    ldx #0
Loop:         // The loop label can’t be seen from the outside
    sta screen,x
    sta screen+$100,x
    sta screen+$200,x
    sta screen+$300,x
    inx
    bne Loop
}
```

--------------------------------

### Include and Play SID Music Files in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch10s10

This code snippet demonstrates how to include SID music files as memory blocks using the 'sidFiles' parameter in KickAssembler. It then uses BASIC UPSTART 2 to start the playback routine at address $1000 and continuously loops to manage music playback and screen updates.

```kickassembler
.segment Main [sidFiles="data/music.sid", outPrg="out.prg"]

BasicUpstart2(start)

start:
        sei
        lda #00
        tax
        tay
        jsr $1000

loop:
        lda #$f0
        cmp $d012
        bne loop
        inc $d020
        jsr $1003
        dec $d020
        jmp loop

```

--------------------------------

### Load Binary File Using Predefined Format Constant

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s02

Demonstrates loading a binary file using a built-in Kick Assembler constant, BF_FLI, which represents a specific file format (likely for FLI animations). This simplifies the loading process by abstracting the template string.

```kickassembler
.var fliPicture = LoadBinary("GreatPicture", BF_FLI)
```

--------------------------------

### Null Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Demonstrates the Null value type, representing the absence of a value.

```KickAssembler
null
```

--------------------------------

### Boolean Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Illustrates the Boolean value type, which can be either true or false.

```KickAssembler
true
```

--------------------------------

### Implement IArchive Interface for Plugin Archiving (Java)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s05s05

This snippet demonstrates the implementation of the IArchive interface in Java, which is used to group multiple plugins into a single archive. It requires implementing the getPluginObjects() method to return a list of IPlugin objects. This allows for streamlined plugin registration.

```java
public interface IArchive extends IPlugin {
   public List<IPlugin> getPluginObjects();
}
```

```java
public class MyArchive implements IArchive{
   @Override
   public List<Object> getPluginObjects() {
      List<Object> list = new ArrayList<Object>();
      list.add(new MyMacro());
      list.add(new MyModifyer());
      return list;
   }
}
```

--------------------------------

### Matrix Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Shows the Matrix value type, specifically representing a 4x4 matrix.

```KickAssembler
Matrix()
```

--------------------------------

### KickAssembler .for Directive: Basic Loop and Data Generation

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch05s04

Demonstrates the basic syntax of the .for directive for creating loops and generating data. It shows how to print numbers sequentially and how to create data for a sine wave using mathematical functions.

```kickassembler
.for(var i=0;i<10;i++)  .print "Number " + i  

.for(var i=0;i<256;i++) .byte round(127.5+127.5*sin(toRadians(360*i/256)))
```

--------------------------------

### Configure Disk Image with Name and ID in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch11s05

This snippet shows how to specify additional parameters for a disk image, such as its name and ID. These parameters are provided as a comma-separated list within the square brackets of the .disk directive. The disk name and ID are visible in the disk's directory.

```kickassembler
.disk [filename="MyDisk.d64", name="THE DISK", id="2021!"] 
{
}
```

--------------------------------

### String Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Shows the String value type, representing textual data enclosed in double quotes.

```KickAssembler
"Hello"
```

--------------------------------

### Create and Write to a File with KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s05

Demonstrates the basic usage of the createFile function to create a file named 'breakpoints.txt' and write a line of text to it using writeln(). Requires the -afo command-line switch for file generation.

```kickassembler
.var myFile = createFile("breakpoints.txt") 
.eval myFile.writeln("Hello World")
```

--------------------------------

### Char Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Shows the Char value type, representing a single character enclosed in single quotes.

```KickAssembler
'x'
```

--------------------------------

### Import Data with Offset and Length (Kick Assembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch03s09

Illustrates advanced usage of the .import directive in Kick Assembler, allowing for optional offset and length parameters. This enables importing specific portions of binary, C64, or text files.

```kickassembler
// import the bytes from the file 'music.bin', but skip the first 100 bytes
.import binary "Music.bin", 100

// Imports $200 bytes starting from position $402 (the two extra bytes is because its a c64 file)  
.import c64 "charset.c64", $400, $200
```

--------------------------------

### BinaryFile Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Demonstrates the BinaryFile value type, which holds byte data. It is typically used with the LoadBinary function.

```KickAssembler
LoadBinary("file.bin", "")
```

--------------------------------

### IEngine Interface

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch17s04

The IEngine interface provides methods for interacting with the Kick Assembler environment, including reporting errors, printing messages, managing memory, and handling file operations.

```APIDOC
## IEngine Interface

### Description
The IEngine interface is the central object for communicating with Kick Assembler. It allows you to report errors, print text to the console, create output streams for files, and manage memory blocks.

### Methods

- **void addError(String message, ISourceRange range)**
  - Description: Adds an error to the engine's error list but allows execution to continue. Useful for reporting multiple errors from a plugin.
- **byte charToByte(char c)**
  - Description: Converts a character to its PETSCII byte representation (uppercase).
- **IMemoryBlock createMemoryBlock(String name, int startAddr, byte[] bytes)**
  - Description: Creates a memory block, often used as a result in some plugins.
- **void error(String message)**
  - Description: Prints an error message and stops execution. Throws an AsmException that must be handled.
- **void error(String message, ISourceRange)**
  - Description: Similar to `error(String message)`, but includes a specific source code range for the error.
- **File getCurrentDirectory()**
  - Description: Retrieves the current working directory.
- **File getFile(String filename)**
  - Description: Opens a file by its filename. The assembler searches in the current directory and then library directories. Returns null if the file is not found.
- **String normalizeFileName(String name)**
  - Description: Evaluates parameters within a filename string. For example, it can replace placeholders like `%o` with the assembly file name.
- **OutputStream openOutputStream(String name) throws Exception**
  - Description: Creates an output stream for writing data, such as creating a disk file for a disk writer.
- **void print(String message)**
  - Description: Prints a message to the screen, similar to the `.print` directive.
- **void printNow(String message)**
  - Description: Prints a message to the screen immediately, similar to the `.printnow` directive.
- **byte[] stringToBytes(String str)**
  - Description: Converts a string to its PETSCII byte representation (uppercase).
```

--------------------------------

### Load Binary File with Template and Access Named Blocks

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s02

Loads a binary file using a template string that defines named memory blocks (Xcoord, Ycoord, BounceData) with their respective offsets. It then demonstrates filling memory regions based on the size and content of these blocks.

```kickassembler
.var dataTemplate = "Xcoord=0,Ycoord=$100, BounceData=$200"
.var file = LoadBinary(“moveData”, dataTemplate)
Xcoord:     .fill file.getXCoordSize(), file.getXCoord(i) 
Ycoord:     .fill file.getYCoordSize(), file.getYCoord(i) 
BounceData: .fill file.getBounceDataSize(), file.getBounceData(i)
```

--------------------------------

### Picture Value Type Example

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas05

Shows the Picture value type, representing the content of a loaded image file. The LoadPicture function is used for this purpose.

```KickAssembler
LoadPicture("blob.gif")
```

--------------------------------

### Load and Dump Binary File Content

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch12s02

Loads an entire binary file into a variable named 'data' and then dumps its content to memory. The .fill directive iterates through the file's size, using .get(i) to retrieve each byte.

```kickassembler
.var data = LoadBinary("myDataFile")

myData: .fill data.getSize(), data.get(i)
```

--------------------------------

### Define Disk and File Parameters (KickAssembler)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch11s06

This snippet demonstrates how to define a disk image and its contents using KickAssembler's `.disk` directive. It shows how to specify file names, types (program, relative, etc.), and link them to memory segments or external files. It also illustrates options like hiding files and locking them.

```kickassembler
.disk [filename="MyDisk.d64", name="THE DISK", id="2021!" ] 
{
        [name="----------------", type="rel"                            ],
        [name="BORDER COLORS   ", type="prg",  segments="BORDER_COLORS" ],
        [name="BACK COLORS     ", type="prg<", segments="BACK_COLORS"   ],
        [name="HIDDEN          ", type="prg",  hide, segments="HIDDEN"  ],
        [name="----------------", type="rel"                            ],
        [name="MUSIC FROM PRG  ", type="prg", prgFiles="data/music.prg" ],
        [name="MUSIC FROM SID  ", type="prg", sidFiles="data/music.sid" ],
        [name="----------------", type="rel"                            ],
}

        .segment BORDER_COLORS []
        BasicUpstart2(start1) 
start1:
        inc $d020
        jmp *-3

        .segment BACK_COLORS []
        BasicUpstart2(start2) 
start2:
        dec $d021
        jmp *-3

        .segment HIDDEN []
        .text "THIS IS THE HIDDEN MESSAGE!"

```

--------------------------------

### Get Current Namespace Name in KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch09s02

Shows how to use the getNamespace() function in KickAssembler to retrieve the name of the current namespace. This is useful for debugging or conditional logic based on the current scope.

```assembly
.print "Namespace = "+getNamespace()
.namespace MySpace {
   .print "Namespace = "+getNamespace()
   .namespace MySubSpace {
      .print "Namespace = "+getNamespace()
   }
}
```

--------------------------------

### Function Return Directive (.return)

Source: https://www.theweb.dk/KickAssembler/webhelp/content/apas04

Used within functions defined by the '.function' directive to return a value to the caller. Example: '.return 27' returns the value 27 from the current function.

```kickassembler
.return 27
```

--------------------------------

### Create an Immediate Argument with KickAssembler

Source: https://www.theweb.dk/KickAssembler/webhelp/content/ch07s03

Demonstrates creating a new command argument, specifically an immediate argument with a value of 100, using the CmdArgument function in KickAssembler. This generated argument can then be used in instructions like LDA.

```kickassembler
.var myArgument = CmdArgument(AT_IMMEDIATE, 100)
lda myArgument   // Gives lda #100

```
Tokens:
Raw