Script Format: Difference between revisions

Latest revision as of 16:37, 13 September 2026

Scripts are parsed bytewise.

A note about event flags

Event flags are calculated from an u16 value like this:

u16 EventFlag;

Flag  = (EventFlag & 0xFFF) >> 3;
Value = 1 << (EventFlag & 7);
IsSet = EventFlag & 0x8000

Commands

Opcode

Function

Length

Comments

00

Call

4

This command has no stack for return addresses. Nested calls simply overwrite any previous return address, so return is only possible to the most recent call site.

If a simple jump is desired, use command 06 for an async jump, or ASM BRA or JMP for an instantaneous jump.

01

ReturnFrom00

1

If not inside 00-Call, this command is ignored.

02

LoopSetup( u16 Count )

3

03

LoopDoAsync()

1

04

LoopDo()

1

05

WaitOnEventFlag( u16 Flag )

3

06

JumpAndSetOrigin

4

07

EventFlagModify

3

08

EventFlagCheckJump

5

09

EventFlagCheckMultiple

3+2*x

0A

CheckMapID

5

0B

CheckDeathwarpMapID

5

0C

TriggerOnAreaAbsolute

8

0D

TriggerOnAreaRelative

8

0E

TriggerOnAreaAbsolutePixel

12

0F

TriggerOnBlockAbsolute

6

10

TriggerOnBlockRelative

6

11

TriggerObjectOnAreaAbsolute

8

First parameter is object index, which is multiplied by 40 and added to 1000 to get the object handle, for which the trigger is checked.

Remaining parameters are same as command 0C.

12

TriggerObjectOnAreaRelative

8

Broken command.

Supposed to be 0D-counterpart of 11: it should compare the position of the object that is given as first parameter to the position of the object that executes the command, but it uses for both purposes only the object that is given as parameter, which makes it useless.

13

SpriteSetPosition

4

14

PlayerPort

9

15

PlayerPortByEnemy

1

Used by Guardner to port Ark out of towers. Uses byte #15 of the extended sprite definition, see Enemy Induced Warps.

16

SetBonepinWarp( u16, u8, u16, u16 )

8

The bonepin warp location is stored in memory at address 7E0608 (8 bytes, right after the deathwarp location)

17

SeagullTransport( u8 to, u16 src_x, u16 src_y )

6

Includes automatic port to map 5, flight scene and port to the destination map, see Seagull Transport.

18

RideShip( u8 route, u8 direction, u16 src_x, u16 src_y )

7

Includes automatic port to map 2, ship scene and port to destination map, see Automatic Ship Routes

19

RespawnBonePinLocationSet( u16 MapID, u8 Direction, u16 X, u16 Y, u16 MapID, u8 Direction, u16 X, u16 Y )

15

Sets the Death- and Bonepin warp location (7E0600 and 7E0608 respectively).

1A

DialogSwitchChoice( u8 layout, u16 choices_ptr )

4

choices_ptr refers to a table with jump addresses. The text for the choices needs to be created beforehand by a normal text command.

The choices_ptr can also not be directly after this command but after the whole script.

Known layouts are:

Layout	Choices
00	2
01
02
03
04
08	3
09	4
0A	2
0B	2

1B

PrintRelative( u16 Address )

3

1C

PrintAbsolute( u24 Address )

4

1D

u16

3

1E

u8, u16

4

calls 0x1D

1F

MessageWait

1

This waits for a button input for the message to continue/close

20

MessageAuto

1

This automatically continues/closes the message

21

TriggerSet( u16 addr )

3

Trigger is executed when Ark talks to an object. When addr is 0 it is deleted

22

SwitchRange( u8 first, u8 last, ... )

3 + 2*(last+1-first)

Choice is determined by object data byte $26. One 2-byte jump address for each possible choice is directly included in the command.

23

TriggerNearPlayer( u16 addr )

3

Turns NPC towards player and jumps to addr.

24

TriggerNearPlayer( u8, u16 addr )

4

Turns NPC towards player and jumps to addr.

25

Random

1

Calls the randomiser function and returns a value

26

RandomMoveInArea( u8 left, u8 top, u8 right, u8 bottom )

5

27

RandomMoveInArea( u8 animation, u8 ???, u8 left, u8 top, u8 right, u8 bottom )

7

not used by the game

28

2

Set 0x7F2018 to value

29

PadButtonsEnable( u16 buttons )

3

2A

PadButtonsDisable( u16 buttons )

3

2B

PadCheckAllButtonsPressed2

5

2C

PadCheckNoButtonPressed2

5

2D

PadCheckButtonPressed

8

2E

PadCheckAnyButtonPressed

5

2F

PadCheckNoButtonPressed

5

30

MusicPlay

2

31

MusicPlayFadeOver

2

32

MusicPlay2

2

This saves the last track played via this command.

When calling it with the value set to 0xFF it plays the last played track again.

33

WaitMusicLoaded

1

34

APUWriteByte_F5( u8 Byte )

2

Writes one byte to 0x2140 (APUI00) followed by a write with 0xF5

35

APUWriteByte_F6( u8 Byte )

2

Writes one byte to 0x2140 (APUI00) followed by a write with 0xF6

36

SoundEffectPlayOnce

2

37

SoundEffectPlay

2

38

SoundEffect?

3

39

SpriteGotoPositionX

4

This command expects to be followed by "0x8E, 0x3B, asm(BRA -11)" because once it reaches the position it is hardcoded to jump 6 bytes ahead.

3A

SpriteGotoPositionY

4

This command expects to be followed by "0x8E, 0x3B, asm(BRA -11)" because once it reaches the position it is hardcoded to jump 6 bytes ahead.

3B

ObjectSetSolid

1

3C

ObjectSetHollow

1

3D

BlockSetSolid( u8 rel_or_abs, u8 x, u8 y )

4

if rel_or_abs is 00, the coordinate is relative to the current object, for 01 it is absolute.

3E

BlockSetHollow( u8 rel_or_abs, u8 x, u8 y )

4

if rel_or_abs is 00, the coordinate is relative to the current object, for 01 it is absolute.

3F

BlockSetCollision( u8 value, u8 x, u8 y )

4

if (value & 80) is clear, the coordinate is relative to the current object, else it is absolute.

40

DungeonBlockSetHollow( u8 rel_or_abs, u8 x, u8 y )

4

if rel_or_abs is 00, the coordinate is relative to the current object, for 01 it is absolute.

41

BlockCheck( u16 block, u16 addr )

5

Compares 9 least significant bits of block with the block actually under object. If they match, jump to addr.

42

BlockCheckRelative( u8 dx, u8 dy, u16 block, u16 addr )

7

Compares 9 least significant bits of block with the block relative to object. If they match, jump to addr.

43

BlockSetAbsolute( u8 x, u8 y, u16 block )

5

44

BlockSetRelative( u8 dx, u8 dy, u16 block )

5

45

BlockSet

1

Changes the block under object. block = object[7F201A]

46

MapCopyRect( u16 SizeX (Blocks), u16 SizeY (Pixels), u16 SrcX(Blocks), u16 SrcY(Blocks), u16 DstX(Blocks), u16 DstY(Blocks), u8 Unknown )

8

47

ObjectDeleteIfEventFlags

1+2*x

48

ObjectDeleteIfEventFlag( u16 flag )

3

49

ObjectDeleteIfMapID( u16 map )

3

4A

MapFlagCheck( u8 id, u16 minimum, u16 addr )

6

4B

MapFlagUpdate(u8 id, u16 amount )

2 or 4

4C

TownGrowthCheck( u8 id, u16 minimum, u16 addr )

6

Jump to addr if growth rate id is at least the specified minimum.

4D

TownGrowthUpdate( u8 id, u16 amount )

2 or 4

(id & C0) specifies the update mode:

mode	description
00	overwrite
40	subtract
80	add

4E

u16, u16

5

4F

u16, u16

5

50

u16, u8

4

51

52

53

54

ItemAdd( u8 item, u16 addr )

4

Jump to addr if the item can't be carried because the slot or inventory is full.

55

ItemDel( u8 item )

2

56

ItemCheckEmptySlot( u8 id, u16 addr )

4

Jump to addr if the item can't be carried because the slot or inventory is full.

57

ItemCheckOwned( u8 id, u16 addr )

4

Jump to addr if Ark has the item in his inventory.

58

ItemCheckEquipped( u8 id, u16 addr )

2 or 4

Jump to addr if Ark has the item equipped.

59

ObjectCheckOffScreen()

2

5A

PaletteLoad( u8 src_bank, u16 src_addr, u8 dest_color_index, u8 count )

6

5B

DecompressToMemory( u24 src, u16 dest )

6

5C

MoneyAdd( u24 amount )

4

amount is BCD

5D

MoneyTake( u24 amount, u16 addr )

6

amount is BCD. Jump to addr if Ark has not enough money.

5E

MoneyCheck( u24 amount, u8 mode, u16 addr )

7

amount is BCD. The result of the comparison is interpreted according to mode:

mode & C0	action
00	jump if money == amount
40	jump if money < amount
80	jump if money > amount
C0	jump if money != amount

5F

SwitchOnDirection( u16 DownJump, u16 UpJump, u16 LeftJump, u16 RightJump )

9

60

ItemAddPlayMusic( u8 ItemID, u16 Delay, u8 MusicID )

5

61

CheckDirectionEx( u8 direction, u8 a, u8 b, u8 c, u16 jump )

7

Jump if current directon matches. Diagonal movement is acknowledged if it's primarily in the specified direction. direction can be 0-3:

direction
00	down
01	up
02	left
03	right

The values a, b and c correspond to skew directions and are used with object[7F2014] ???

62

SetInvulnerable( u8 frames )

2

63

3

64

3

65

HandlerRegisterOnDamage( u16 HandlerAddress, u24 ReturnAddress )

6

66

ReturnFromDamageHandler

1

67

LightFormSet

2

Valid values 0-8

68

RenderSpriteLoop

2

69

RenderSprite

1

6A

u8, u8

3

6B

PrintRelative2

3

6C

PrintAbsolute2

4

6D

UploadTileData

1

6E

SceneUpdate

1

6F

ScreenShake

1

70

Follow( u16 ptrObject, u16 ptrAnimations )

5

Animations is a table of 3x4 animation id's, that specify what animation to use for every possible (diagonal) movement.

71

Check???( u16, u16, u16 jump )

7

Jumps if the check is successful

72

u16, u8

4

73

5

Wait for unknown condition and then jump

74

SetMagicHandler( u8 magic_id, u16 handler )

4

Registers a handler that is executed when the specific magic is used. If handler & 0x8000 is set, it refers to a script address, else it is a flag that will be set.

object[7F2024] = magic_id
object[7F2022] = handler

75

SetConditionalTalkHandler( u16 flag, u16 handler )

5

custom handler must be >= 0x8000, values below are predefined handlers, but only 0000 is currently used and prints a line of dots.

object[7F2028] = flag
object[7F2026] = handler

76

SystemRegisterWrite

3

77

78

BackgroundUpdateFade

2

79