API note

How about Interaction

zisazsnes uses Microsoft ActiveScript technology to connect this compiled application with script like JScript.

zisazsnes supports only emulated 65816 CPU for debugging.

zisazsnes calls scripts when:

bulletHit a Breakpoint.

The scripts call zisazsnes back when:

bulletSend a message to zisazsnes LOG CONSOLE box.
bulletAdd/remove a Breakpoint.
bulletRead memory/CPU register thru zsnes emulator.
bulletCapture continuous memory to a new file.
bulletFormalize a text.
bulletDo enable/disable: SingleStep, PostProcess

Sample: Send a message to LOG CONSOLE

I recommend JScript (not VBS) to script this. VBS sometimes treats unsigned integer as signed integer.

Next sample is written in JScript.

external.Message("test test", "test", 1);
external.Message(external.CasetteName, "test", 1)

The sample sends 2 messages.

1st message sends literal text "test test".
2nd message sends rom cartridge name.

You can access zisazsnes thru "external" object. In this case, script acquired the cartridge name.

event reference

horizontal rule

OnCodeBreak method

function OnCodeBreak(addr);

Overview:

bulletzisazsnes call the script before execution of emulated code, when one of following condition satisfies.
bulletA Breakpoint hits.
bulletSingleStep feature is active.

Arguments table:

Argument Name Meaning
address An execution address zsnes is wiilling to execute.

horizontal rule

OnCodeBreakPostProcess method

function OnCodeBreakPostProcess(priorAddr, currentAddr);

Overview:

bulletzisazsnes call the script after execution of emulated code, when all of following condition satisfies.
bulletA Breakpoint hits on previously executed code.
bulletPostProcess feature is activate.

Arguments table:

Argument Name Meaning
priorAddr Eve address zsnes executed previously.
currentAddr An execution address zsnes is wiilling to execute.

 

external object reference

horizontal rule

Message method

function external.Message(message, source, severity);

Overview:

bulletSend a text message to LOG CONSOLE.

Arguments table:

Argument Name Meaning
message A literal text to display.
source Source of message sender. This is a kind of FYI. zisazsnes is not interested in the name of sender.
severity Severity value of message:
bullet0 = None
bullet1 = Information
bullet2 = Warning
bullet3 = Error

horizontal rule

AddCodeBreak method

function external.AddCodeBreak(address);

Overview:

bulletAdd a Breakpoint.
bulletEach Breakpoint has reference count.
zisazsnes increases reference count if you set a Breakpoint for already added address.
bulletThe Breakpoint and its reference count are shared with all running scripto.
bulletThe address is execution address. OnCodeBreak and OnCodeBreakPostProcess is called if hits Breakpoint.
bulletCurrent implement supports up to 10 Breakpoints.

Arguments table:

Argument Name Meaning
address An address to new Breakpoint.
Give 0x018000 for address 01/8000.

horizontal rule

RemoveCodeBreak method

function external.RemoveCodeBreak(address);

Overview:

bulletDecrase the reference count of corresponding Breakpoint.
bulletRemove the Breakpoint if reference count is to be 0.

Arguments table:

Argument Name Meaning
address An address for Breakpoint to be removed.

horizontal rule

ReadMem8 method

function external.ReadMem8(address);

Overview:

bulletRead a byte from memory, and return a byte value.
bulletYou can read ROM/RAM address.
bulletThe implementation fully depends on zsnes code.

Arguments table:

Argument Name Meaning
address An address to be read.

horizontal rule

ReadMem16 method

function external.ReadMem16(address);

Overview:

bulletRead a word value from memory, and return a signed 16-bits value.
bulletYou can read ROM/RAM address.
bulletThe implementation fully depends on zsnes code.

Arguments table:

Argument Name Meaning
address An address to be read.

horizontal rule

ReadMem32 method

function external.ReadMem32(address);

Overview:

bulletRead a double word value from memory, and return a signed 32-bits value.
bulletYou can read ROM/RAM address.
bulletThe implementation fully depends on zsnes code.

Arguments table:

Argument Name Meaning
address An address to be read.

horizontal rule

CaptureMemoryToFile method

function external.CaptureMemoryToFile(addrFrom, addrTo, newFileName);

Overview:

bulletRead continuous memory space.
bulletYou can read ROM/RAM address.
bulletThe implementation fully depends on zsnes code.

Arguments table:

Argument Name Meaning
addrFrom An address to start reading.
addrTo An address to finish reading. The capture contains last byte of addrTo address.
newFileName A filename to be written captured raw data.

horizontal rule

sprintf method

function external.sprintf(format, arrayObject)

Overview:

bulletThe behavior is like sprintf found on C/C++ language.
But current implementation doesn't fully support its format specification.

See also: http://www.opengroup.org/onlinepubs/007908799/xsh/fprintf.html
See also: http://www.cplusplus.com/ref/cstdio/sprintf.htm

Sample:

external.sprintf("%u + %u = %u", new Array(11, 22, 33))

this sample returns "11 + 22 = 33".

Arguments table:

Argument Name Meaning
format The format text.
arrayObject Supports:
bulletVariant objects in SafeArray
bulletAn IDispatch object supports DISPID_NEWENUM method. Also IEnumVariant object.

horizontal rule

EnableSingleStep method

function external.EnableSingleStep()

Overview:

bulletEnable SingleStep feature.
bulletIncrease the reference count.
bulletCall OnCodeBreak method on each single step in emulator.

Arguments table:

No argument required.

horizontal rule

DisableSingleStep method

function external.DisableSingleStep()

Overview:

bulletDisable SingleStep feature if reference count decrased to zero.
bulletDecrase the reference count.

Arguments table:

No argument required.

horizontal rule

EnablePostProcess method

function external.EnablePostProcess()

Overview:

bulletEnable PostProcess feature.
bulletCall OnCodeBreakPostProcess method on next execution after previous Breakpoint passes.
bulletIncrease the reference count.

Arguments table:

No argument required.

horizontal rule

DisablePostProcess method

function external.DisablePostProcess()

Overview:

bulletDisable PostProcess feature if reference count decrased to 0.
bulletDecrease the reference count.

Arguments table:

No argument required.

horizontal rule

xa property

function external.xa()

Overview:

bulletReturns A register (16-bits).

horizontal rule

xdb property

function external.xdb()

Overview:

bulletReturns DataBank register (8-bits).

horizontal rule

xpb property

function external.xpb()

Overview:

bulletReturns ProgramBank register (8-bits).

horizontal rule

xs property

function external.xs()

Overview:

bulletReturns Stack register (16-bits).

horizontal rule

xd property

function external.xd()

Overview:

bulletReturns Direct register (16-bits).

horizontal rule

xx property

function external.xx()

Overview:

bulletReturns X register (16-bits).

horizontal rule

xy property

function external.xy()

Overview:

bulletReturns Y register (16-bits).

horizontal rule

CasetteName property

function external.CasetteName()

Overview:

bulletReturns casette name described in rom file.

horizontal rule

PrevAddr property

function external.PrevAddr()

Overview:

bulletReturns an address on previous execution.