YACE 64 Script Automation Reference

The Commodore 64 and 1541 emulator can be controlled with scripts in many ways. All you need is a little experience with the C# or Visual Basic language.
The script offer functions to set breakpoint, create screenshots, send keyboard command, let the emulator pause at various conditions and much more.
Script function are called when breakpoint are reached, diverse informations and one of the three possible custom button are pressed by the user.

Scriptbase

A script can be create in C# or in Visual Basic. The script must be derived from ScriptBase and can implement callback functions to react on system events.
Scripts can be edit with the build-in editor of YACE64.
The following script shows the outline of a script and describes the possible callbacks:

using System;
using YACEAutomation;

public class Script : ScriptBase
{
    //
    // Called when the script is created
    //
    public Script()
    {
    }

    //
    // Called when the script was loaded
    //
    public override void onStart()
    {
        // Global.BreakCycle = Global.Cycle + 2000000;
    }

    //
    // Called when the script will be unloaded
    //
    public override void onStop()
    {
       // C64.clearBreakpoint(0xEA81);
    }

    //
    // Called when the debugger enters a break condition
    //
    // system: C64, Drive8, Drive9
    // address: Current CPU opcode address
    // rasterline: 0-311
    // rasterCycle: 0-129 (half cycles)
    // reason: Operation, MemoryRead, MemoryWrite, Rasterline, Frame, Cycle, User or Save
    //
    // To get more informations call the properties of C64, Drive8, Drive9 or Global object
    //
    public override void onBreak(string system, int address, int rasterline, int rasterCycle, string reason, string message)
    {
      //App.showMessage(MessageFormat.Info, MessageChoose.Ok, "Break",reason);
       //Global.BreakCycle = Global.Cycle + 2000000;
    }

    // Called when a system info occured
    // This callback delivers informations about diverse state e.g. like current track number of disc drive
    // system: Name of the system, that triggered the breakpoint. (C64, 1541-8, 1541-9)
    // infoType: Enumeration 'InfoType' with one of this values: Undefined,DriveTrack,DriveLED,DriveMotor,DiscModified,DiscChanged
    // infoData: Value according to the 'infoType'. Can be int (e.g. track number or bool e.g. LED on or off)
    public override void onInfo(string system, InfoType infoType, object infoData)
    {
       // App.showMessage(MessageFormat.Info, MessageChoose.Ok, ""Info"",string.Format(""{0}: {1} = {2}"", system, infoType, infoData));
    }

    //
    // Called when a user button is pressed
    //
    // The buttonIndex is 0, 1 or 2.
    //
    public override void onButton(int buttonIndex)
    {
       // C64.createSnapshot("i:\\temp\\test.bmp");
       // App.startCapture(30);
       // App.showMessage(MessageFormat.Info, MessageChoose.Ok, "Note",string.Format("Button {0} pressed", buttonIndex));
    }

    //
    // Called when a frame was rendered
    //
    public override void onFrameEnd()
    {
    }

    //
    // Return the names of the user buttons (maximum 3)
    //
    // Setting a name to null, hides the button.
    //
    public override string[] Buttons
    {
       get
       {
           return (new string[]{"Test1", "Test2"});
       }
    }
}


Callbacks

For a detailed desciption of all parameters see the comments in the code above.
Callback Short description Description
onStart() The script was loaded
onStop() The script will be unloaded
onBreak() Called when the debugger
enters a break condition		 Possible conditions are:
Operation-Breakpoint
MemoryRead-Breakpoint
MemoryWrite-Breakpoint
Rasterline-Breakpoint
Frame
Cycle-Breakpoint
User paused
onInfo() A system info occured This callback delivers informations about diverse
states e.g. like current track number of disc drive, LED, Motor, etc
onFrameEnd() A frame was rendered

Objects

Within the script the following object are provided to access the application and the emulated systems:

App

showMessage

Format

MessageResult showMessage(MessageFormat messageFormat, MessageChoose messageChoose, string caption, string message)

Description

Shows a message box and lets the user select an action.
If another message box is still open, no other message box is shown. showmessage() returns messageresult.ignored in this case.

Parameter Description
messageFormat : MessageFormat Info, Warning, Error
messageChoose : MessageChoose Ok, OkCancel, YesNo
caption : string Title of the box
message : string Text of the box
Returns : MessageResult Ok, Cancel, Yes, No, None, Ignored

Example:

if (App.showMessage(MessageFormat.Info, MessageChoose.Ok, "Title", "Hello")==MessageResult.Ok)
{
}

startCapture

Format

void startCapture(string filenameAndPath, int maxLengthSeconds)

Description

Start capturing audio and video.
An AVI File will be created with a given filename. Depending on the installed codecs the video will be compressed.
xvid should be used for a fast and good compression. Only codecs that support compression of 24 or 32 bit RGB images are supported.

Parameter Description
filenameAndPath : string Name of the filename and the path, file will always be overriden
maxLengthSeconds : int Automatic stop after given number of seconds

Example:

App.startCapture("Screen.avi", 60);

startCapture

Format

void startCapture(int maxLengthSeconds)

Description

Start capturing audio and video.
AVI File will be created in the "Documents\YACE" folder. Depending on the installed codecs the video will be compressed.
xvid should be used for a fast and good compression. Only codecs that support compression of 24 or 32 bit RGB images are supported.

Parameter Description
maxLengthSeconds : int Automatic stop after given number of seconds

Example:

App.startCapture(60);

stopCapture

Format

void stopCapture()

Description

Stop capturing audio and video.

Parameter Description

Example:

App.stopCapture();

unloadScript

Format

void unloadScript()

Description

Unload the current script.
Script will stop as soon as possible and onStop() will be called.

Parameter Description

Example:

App.unloadScript();

loadScriptCS

Format

void loadScriptCS(string fileNameAndPath)

Description

Load a new C# script.
Current script will stop as soon as possible and onStop() will be called before loading the new script.

Parameter Description
fileNameAndPath : string Filename and path

Example:

App.loadScriptCS("test.cs");

loadScriptCS

Format

void loadScriptVB(string fileNameAndPath)

Description

Load a new Visual Basic script.
Current script will stop as soon as possible and onStop() will be called before loading the new script.

Parameter Description
fileNameAndPath : string Filename and path

Example:

App.loadScriptVB("test.vb");

saveState

Format

void saveState(string fileNameAndPath)

Description

Save the current state.


Parameter Description
fileNameAndPath : string Filename and path

Example:

App.saveState("test.yace");

loadState

Format

void loadState(string fileNameAndPath)

Description

Load a saved state.


Parameter Description
fileNameAndPath : string Filename and path

Example:

App.loadState("test.yace");

load

Format

void load(string fileNameAndPath)

Description

Loads a disc image or program file.
Program (.prg, .t64) files are loaded directly into memory. Disc images (.g64, .d64) are loaded into the selected drive.
Note: Changes on the current disc are lost, if the disc isn't saved before.

Parameter Description
fileNameAndPath : string Filename and path

Example:

App.load("demo.g64");
// or
App.load("demo.prg");

searchAndLoad

Format

void searchAndLoad(string fileName)

Description

Loads a disc image or program file.
Program (.prg, .t64) files are loaded directly into memory. Disc images (.g64, .d64) are loaded into the selected drive.

Parameter Description
fileName : string Filename to be searched in Diskimage folder (see configuration).
Returns : bool true if the file was found.

Example:

if (App.searchAndLoad("demo.g64"))
{
}

SelectedDrive

Format

int SelectedDrive

Description

Gets or sets the selected disc drive.
Load operations will be done on the selected drive.

Parameter Description
get : int Device ID, must be 8 or 9.
set : int Device ID, must be 8 or 9.

Example:

App.SelectedDrive = 8;

InputPort1

Format

int InputPort1

Description

Gets or sets the selected input device for port 1.
The only wellknow device is the keyboard, all others may not be available on other configurations.

Parameter Description
get : int 0 = No device; 1 = Keyboard; 2...n = optional devices.
set : int 0 = No device; 1 = Keyboard; 2...n = optional devices.

Example:

App.InputPort1 = 1;

InputPort2

Format

int InputPort2

Description

Gets or sets the selected input device for port 2.
The only wellknow device is the keyboard, all others may not be available on other configurations.

Parameter Description
get : int 0 = No device; 1 = Keyboard; 2...n = optional devices.
set : int 0 = No device; 1 = Keyboard; 2...n = optional devices.

Example:

App.InputPort2 = 0;



Global

NTSC

Format

bool NTSC

Description

Set NTSC timing.
Switching the timing can cause undesired effects on a running emulation!

Parameter Description
get : bool true = NTSC, false = PAL
set : bool true = NTSC, false = PAL

Example:

Global.NTSC = true;

Speed

Format

Speed Speed

Description

Sets the emulators speed.

Parameter Description
get : Speed Normal, Maximum, Half, Quarter, Tens
set : Speed Normal, Maximum, Half, Quarter, Tens

Example:

Global.Speed = Speed.Normal;

Cycle

Format

uint Cycle

Description

Current cycle time index (full cycle)

Parameter Description
get : uint 1/1000000s since start (depending on PAL or NTSC)

Example:

if (Global.Cycle > 10000000) // about 10s after start
{
}

BreakCycle

Format

uint BreakCycle

Description

Sets a breakpoint for a specific cycle time index.
One cycle is about 1 micro second (depending on PAL or NTSC).
The emulator will pause when this time is reaches and onBreak() will be called.

Parameter Description
get : uint 1/1000000s since start (depending on PAL or NTSC)
set : uint 1/1000000s since start (depending on PAL or NTSC)

Example:

Global.BreakCycle = Global.Cycle + 1000000; // Break every ~1s



C64, Drive8, Drive9

These functions are the available on all three objects.
Specific function on theses devices can be found here: C64, Drive8 and Drive9

getTraceModules

Format

string[] getTraceModules()

Description

Get the available trace module names.

Parameter Description
Returns : string[] String array of the names

Example:

string[] modules = C64.getTraceModules(); // also Drive8 or Drive9

setTraceLevelDebug

Format

bool setTraceLevelDebug(string moduleName)

Description

Sets the 'Debug' level for the given module.
This is the highest level and degrades the performance.

Parameter Description
moduleName : string Name of the module (see getTraceModules())
Returns : true true, if level was set

Example:

C64.setTraceLevelDebug("SID"));

setTraceLevelError

Format

bool setTraceLevelError(string moduleName)

Description

Sets the 'Error' level for the given module.

Parameter Description
moduleName : string Name of the module (see getTraceModules())
Returns : true true, if level was set

Example:

C64.setTraceLevelError("CPU"));

setTraceLevelWarning

Format

bool setTraceLevelWarning(string moduleName)

Description

Sets the 'Warning' level for the given module.

Parameter Description
moduleName : string Name of the module (see getTraceModules())
Returns : true true, if level was set

Example:

C64.setTraceLevelWarning("CPU"));

setTraceLevelInfo

Format

bool setTraceLevelInfo(string moduleName)

Description

Sets the 'Information' level for the given module.

Parameter Description
moduleName : string Name of the module (see getTraceModules())
Returns : true true, if level was set

Example:

C64.setTraceLevelInfo("CPU"));

setTraceLevelVerbose

Format

bool setTraceLevelVerbose(string moduleName)

Description

Sets the 'Verbose' level for the given module.

Parameter Description
moduleName : string Name of the module (see getTraceModules())
Returns : true true, if level was set

Example:

C64.setTraceLevelVerbose("CPU"));

RegisterPC

Format

int RegisterPC

Description

Get the programcounter.

Parameter Description
get : int Current programcounter 0-65535

Example:

int address = Drive8.RegisterPC;

RegisterSP

Format

byte RegisterSP

Description

Get the stackpointer.

Parameter Description
get : byte Current stackpointer 0-255

Example:

byte stackPointer = Drive8.RegisterSP;

RegisterA

Format

byte RegisterA

Description

Get the accumulator.

Parameter Description
get : byte Current accumulator 0-255

Example:

byte accu = C64.RegisterA;

RegisterX

Format

byte RegisterX

Description

Get the index X register.

Parameter Description
get : byte Current index X register 0-255

Example:

byte accu = C64.RegisterX;

RegisterY

Format

byte RegisterY

Description

Get the index Y register.

Parameter Description
get : byte Current index Y register 0-255

Example:

byte accu = C64.RegisterY;

FlagZ

Format

bool FlagZ

Description

Get the Zero flag.

Parameter Description
get : bool true, Zero flag is set

Example:

bool isZero = C64.FlagZ;

FlagN

Format

bool FlagN

Description

Get the Negative flag.

Parameter Description
get : bool true, Negative flag is set

Example:

bool isNegative = C64.FlagN;

FlagV

Format

bool FlagV

Description

Get the oVerflow flag.

Parameter Description
get : bool true, oVerflow flag is set

Example:

bool isOverflow = C64.FlagV;

FlagI

Format

bool FlagI

Description

Get the Interrupt flag.

Parameter Description
get : bool true, Interrupt flag is set

Example:

bool isInterruptBlocked = C64.FlagI;

FlagD

Format

bool FlagD

Description

Get the Decimal flag.

Parameter Description
get : bool true, Decimal flag is set

Example:

bool isDecimalMode = C64.FlagD;

FlagC

Format

bool FlagC

Description

Get the Carry flag.

Parameter Description
get : bool true, Carry flag is set

Example:

bool isCarry = C64.FlagC;

FlagB

Format

bool FlagB

Description

Get the Break flag.

Parameter Description
get : bool true, Break flag is set

Example:

bool isBreak = C64.FlagB;

setBreakpoint

Format

void setBreakpoint(int address)

Description

Sets a breakpoint at a specified address.

Parameter Description
address : int 0-65535

Example:

C64.setBreakpoint(0xEA81);

clearBreakpoint

Format

void clearBreakpoint(int address)

Description

Clears a breakpoint at a specified address.

Parameter Description
address : int 0-65535

Example:

C64.clearBreakpoint(0xEA81);

getBreakpoint

Format

bool getBreakpoint(int address)

Description

Check if a breakpoint is set at the specified address.

Parameter Description
address : int 0-65535
Returns : bool true, if a breakpoint is set

Example:

bool isBreakpointSet = C64.getBreakpoint(0xEA81);

setOperationAddressName

Format

void setOperationAddressName(int address, string name)

Description

Sets a name for an address.
Note: There are several names already set, espacially for the Kernal ROM routines.

Parameter Description
address : int 0-65535
name : string Name that will be logged in a trace and a disassembly,
when the CPU operates on the address

Example:

C64.setOperationAddressName(0xEA81, "IRQ");

getOperationAddressName

Format

string getOperationAddressName(int address)

Description

Sets a name for an address.

Parameter Description
address : int 0-65535
Returns : string Name of the address

Example:

string name = C64.getOperationAddressName(0xEA81);

setOperationAddressComment

Format

void setOperationAddressComment(int address, string comment)

Description

Sets a comment for an address.

Parameter Description
address : int 0-65535
comment : string Comment that will be logged in a trace and a disassembly,
when the address is accessed

Example:

C64.setOperationAddressComment(0xEA81, "IRQ Routine");

getOperationAddressComment

Format

string getOperationAddressComment(int address)

Description

Sets a comment for an address.

Parameter Description
address : int 0-65535
Returns : string Comment of the address

Example:

string comment = C64.getOperationAddressComment(0xEA81);

readMemory

Format

byte readMemory(int address)

Description

Reads the content of the memory or device.
The byte is read from the memory according to the current memory configuration.
This means that the functions reads the memory as if the CPU would read it from the bus.

Parameter Description
address : int 0-65535
Returns : byte Databyte 0-255

Example:

byte data = C64.readMemory(0x0000);

writeMemory

Format

void writeMemory(int address, byte value)

Description

Writes a byte to the memory or device.
The byte is written into memory according to the current memory configuration.
This means that the functions writes the memory as if the CPU would write it to the bus.

Parameter Description
address : int 0-65535
value : byte Databyte 0-255

Example:

C64.writeMemory(0x0000, 0x00);

setMemoryReadBreakpoint

Format

void setMemoryReadBreakpoint(int address)

Description

Sets a breakpoint for a read operation to the data bus.

Parameter Description
address : int 0-65535

Example:

C64.setMemoryReadBreakpoint(0x0000);

clearMemoryReadBreakpoint

Format

void clearMemoryReadBreakpoint(int address)

Description

Clears a breakpoint for a read operation to the data bus.

Parameter Description
address : int 0-65535

Example:

C64.clearMemoryReadBreakpoint(0x0000);

getMemoryReadBreakpoint

Format

bool getMemoryReadBreakpoint(int address)

Description

Checks if a breakpoint is set for a read operation to the data bus.

Parameter Description
address : int 0-65535
returns : bool true, if a breakpoint is set

Example:

bool breakpointSet = C64.getMemoryReadBreakpoint(0x0000);

setMemoryWriteBreakpoint

Format

void setMemoryWriteBreakpoint(int address)

Description

Sets a breakpoint for a write operation to the data bus.

Parameter Description
address : int 0-65535

Example:

C64.setMemoryWriteBreakpoint(0x0000);

clearMemoryWriteBreakpoint

Format

void clearMemoryWriteBreakpoint(int address)

Description

Clears a breakpoint for a write operation to the data bus.

Parameter Description
address : int 0-65535

Example:

C64.clearMemoryWriteBreakpoint(0x0000);

getMemoryWriteBreakpoint

Format

bool getMemoryWriteBreakpoint(int address)

Description

Checks if a breakpoint is set for a write operation to the data bus.

Parameter Description
address : int 0-65535
returns : bool true, if a breakpoint is set

Example:

bool breakpointSet = C64.getMemoryWriteBreakpoint(0x0000);

reset

Format

void reset()

Description

Trigger a reset.

Parameter Description

Example:

C64.reset();

step

Format

void step()

Description

Performs a single assembler step, when a breakpoint was reached.

Parameter Description

Example:

C64.step();

run

Format

void run()

Description

Continues running, when a breakpoint was reached.

Parameter Description

Example:

C64.run();

pause

Format

void pause()

Description

Stops running, like when a breakpoint was reached.

Parameter Description

Example:

C64.pause();

Paused

Format

bool Paused

Description

Checks, if the system is currently paused (a breakpoint was reached).

Parameter Description
returns : bool true, if system is paused

Example:

bool isPaused = C64.Paused;


C64

sendText

Format

void sendText(string asciiText)

Description

Send simulated keystrokes to the keyboard.

Parameter Description
asciiText : string ASCII Text

Example:

C64.sendText("LOAD""*"",8,1\n");

setKeyboard

Format

void setKeyboard(uint code)

Description

Pushes key down.

Parameter Description
code : uint Keyboardcode

Example:

C64.setKeyboard(0x4002); // E

releaseKeyboard

Format

void releaseKeyboard(uint code)

Description

Releases key up.

Parameter Description
code : uint Keyboardcode

Example:

C64.releaseKeyboard(0x4002); // E

setJoystick

Format

void setJoystick(JoystickPort port, JoystickContact joystick)

Description

Set Joystick contacts.

Parameter Description
port : JoystickPort Port1, Port2
joystick : JoystickContact
(Flags)		 JoystickLeft, JoystickRight, JoystickUp, JoystickDown, JoystickFire

Example:

C64.setJoystick(JoystickPort.Port1, JoystickContact.JoystickLeft|JoystickContact.JoystickRight);

releaseJoystick

Format

void releaseJoystick(JoystickPort port, JoystickContact joystick)

Description

Release Joystick contacts.

Parameter Description
port : JoystickPort Port1, Port2
joystick : JoystickContact
(Flags)		 JoystickLeft, JoystickRight, JoystickUp, JoystickDown, JoystickFire

Example:

C64.releaseJoystick(JoystickPort.Port1, JoystickContact.JoystickLeft|JoystickContact.JoystickRight);

enableScreenTrace

Format

void enableScreenTrace()

Description

Enable VIC debugger.
System will stop after every frame.

Parameter Description

Example:

C64.enableScreenTrace();

disableScreenTrace

Format

void disableScreenTrace()

Description

Disable VIC debugger.
System will stop after every frame.

Parameter Description

Example:

C64.disableScreenTrace();

setRasterlineBreakpoint

Format

void setRasterlineBreakpoint(int rasterline)

Description

Set a breakpoint for a specific rasterline.

Parameter Description
rasterline : int Rasterline number 0-311

Example:

C64.setRasterlineBreakpoint(50);

clearRasterlineBreakpoint

Format

void clearRasterlineBreakpoint(int rasterline)

Description

Clears a breakpoint for a specific rasterline.

Parameter Description
rasterline : int Rasterline number 0-311

Example:

C64.clearRasterlineBreakpoint(50);

setREU

Format

void setREU(int sizeKB)

Description

Installs a REU (RAM Expansion Unit) with the given size.
Installing or removing a REU can corrupt a running emulation!

Parameter Description
sizeKB : int Size in KBytes (0,64,128,256,512). 0 removes the REU

Example:

C64.setREU(128);

createSnapshot

Format

void createSnapshot(string filenameAndPath)

Description

Creates a snapshot as bitmap file.

Parameter Description
filenameAndPath : string Name of the filename and the path, file will always be overriden

Example:

C64.createSnapshot("Screen.bmp");



Drive8 and Drive9

Eject

Format

void Eject()

Description

Removes the disc from the drive.
Note: Changes on the disc are lost, if the disc isn't saved before.

Parameter Description

Example:

Drive8.Eject();

Empty

Format

void Empty()

Description

Inserts an empty (unformatted) disc into drive.
Note: Changes on the disc are lost, if the disc isn't saved before.

Parameter Description

Example:

Drive8.Empty();

DiscFile

Format

string DiscFile

Description

Gets the filename of the currently inserted disc file.

Parameter Description
Returns : string Name and path of the disc file

Example:

string discFile = Drive8.DiscFile;

powerOff

Format

void powerOff()

Description

Turns the drive off.

Parameter Description

Example:

Drive8.powerOff();

powerOn

Format

void powerOn()

Description

Turns the drive on.

Parameter Description

Example:

Drive8.powerOn();

WriteProtection

Format

bool WriteProtection

Description

Sets or clears the write protection of the disc.

Parameter Description
set : bool true, to turn write protection on

Example:

Drive8.WriteProtection = true;

saveDisc

Format

void saveDisc(string g64FileNameAndPath)

Description

Saves the current disc to a G64 file.

Parameter Description
g64FileNameAndPath : string Name of the filename and the path, file will always be overriden

Example:

Drive8.saveDisc("MyDisc");