Script Format

From Terranigma Wiki
Jump to navigation Jump to search

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 9 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 9 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.

Known layouts are:

Layout Choices
00 2
01
02
03
04
08 3
09 4
0A 2
0B
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 Rand 1
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 ) 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 ) 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 ) 4 Jump to addr if Ark has the item equipped.
59 ObjectCheckOffScreen() 1
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
65 HandlerRegisterOnDamage( u16 HandlerAddress, u24 ReturnAddress ) 6
66 ReturnFromDamageHandler 1
67 LightFormSet 1 Valid values 0-8
68
69 1
6A u8, u8 3
6B PrintRelative2 3
6C PrintAbsolute2 4
6D
6E SceneUpdate 1
6F 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 Broken command, stubbed in non Japan version
7A Broken command, stubbed in non Japan version
7B Broken command, stubbed in non Japan version
7C Broken command, stubbed in non Japan version
7D Broken command, stubbed in non Japan version
7E Broken command, stubbed in non Japan version
7F Broken command, stubbed in non Japan version
80 AnimationSetSpriteFlagsAndResetElevationLevel( u8 SpriteFlags ) 2
81 AnimationSetB( u8 SpriteFlags ) 2
82 AnimationSetC( u8 SpriteFlags, u8 ) 3
83 SpriteSetFlagsAndElevationLevel( u8 SpriteFlags, u8 EleveationLevel ) 3
84 4
85 AnimationSetD 3 calls 80
86 AnimationSetE( u8, u8 ) 3 calls 81
87 ObjectMove( u8, u8, u8 ) 4 calls 82
88 4 calls 83
89 5 calls 84
8A 2
8B 3 calls 8A
8C 2
8D 3 calls 8C
8E AnimationWait 1
8F AnimationWait2 1
90 1 wait for loop
91 1
92 1 wait for loop
93 1
94 1 wait for loop
95 u16, u8, u16, u16, u16, u8 9
96 u16, u16, u16, u16, u16 11
97 u16, u8, u16, ? 6
98 u16, u8, ? 11 Object related
99 ObjectCloneInsertAtBeginSF 6 Insert at begin of list, set script pointer and flags
9A ObjectCloneInsertBeforeSP 4 Insert before current object, set script pointer and parent (implied)
9B ObjectCloneInsertBeforeSFP 6 Insert before current object, set script pointer, flags and parent (implied)
9C ObjectCloneInsertBeforeSRP 8 Insert before current object, set script pointer, relative placement and parent (implied)
9D ObjectCloneInsertBeforeSRFP 10 Insert before current object, set script pointer, relative placement, flags and parent (implied)
9E ObjectCloneInsertBeforeSAP 8 Insert before current object, set script pointer, absolute placement and parent (implied)
9F ObjectCloneInsertBeforeSAFP 10 Insert before current object, set script pointer, absolute placement, flags and parent (implied)
A0 ObjectCloneInsertAtEndSFP 6 Insert at end of list, set script pointer, flags and parent (implied)
A1 ObjectCloneInsertAfterSP 4 Insert after current object, set script pointer and parent (implied)
A2 ObjectCloneInsertAfterSFP 6 Insert after current object, set script pointer, flags and parent (implied)
A3 ObjectCloneInsertAfterSRP 8 Insert after current object, set script pointer, relative placement and parent (implied)
A4 ObjectCloneInsertAfterSRFP 10 Insert after current object, set script pointer, relative placement, flags and parent (implied)

Same handler as 0xE8

A5 ObjectCloneInsertAfterSAP 8 Insert after current object, set script pointer, absolute placement and parent (implied)
A6 ObjectCloneInsertAfterSAFP 10 Insert after current object, set script pointer, absolute placement, flags and parent (implied)
A7 ObjectDelete 1
A8 1
A9
AA 4
AB
AC
AD
AE
AF 2
B0 2 or 5
B1 ObjectMoveHorizontal 3
B2 ObjectMoveVertical 3
B3 ObjectMove 5
B4 SpriteSetUpsideDown 1
B5 SpriteSetDownsideUp 1
B6 SpriteSetFacingRight 1
B7 SpriteSetFacingLeft 1
B8 SpriteFlipVertical 1
B9 SpriteFlipHorizontal 1
BA SpriteSetPriority 2 Allowed values: 0..3 << 4
BB SpriteSetPalette 2 Allowed values: 0..7 << 1
BC MarkOrigin 1
BD MarkOriginAsync 1
BE JumpAndSetOriginWithDelay 6
BF JumpAndSetOriginAsync 4
C0 SetOriginAndEraseDelay 4
C1 Delay 3
C2 JumpIfMapCollisionAbove 3
C3 JumpIfMapCollisionBelow 3
C4 JumpIfMapCollisionLeft 3
C5 JumpIfMapCollisionRight 3
C6 GetCurrentBlockCollision 1 ??
C7 CheckMapCollisionAbove 3 or 9
C8 CheckMapCollisionBelow 3 or 9
C9 CheckMapCollisionLeft 3 or 9
CA CheckMapCollisionRight 3 or 9
CB 5 Change other object script ??
CC 6
CD
CE
CF
D0
D1
D2 TriggerOnSight( u8 SideRange, u8 FrontRange, u8 Direction, u16 JumpAddress ) 6
D3 RangeCheckHorizontal 9
D4 RangeCheckVertical 9
D5
D6 ProximityTrigger 4
D7 DetermineNearestAxis 5
D8 4
D9 LoadFightingStats 2 Load pointer to index in enemy table

80: Don't load max HP

DA HandlerRegisterOnWall( u16 HandlerAddress ) 3 Set Wall Hit Handler
DB
DC ScreenScroll( u16 Type, u8 ScrollX, u8 ScrollY, u8 Speed ) 6
DD 8
DE ScreenReturnScroll( u8 Speed ) 2
DF WaitOn097C_0810 4 Wait For ([097C] & 0810) == 0, Then Jump
E0
E1
E2
E3
E4 1
E5
E6 ObjectCloneDepInsertAfterSP 4 Like A1, but additionally makes new object depend on the old one, which mainly matters for mass deletion with command EB.
E7 ObjectCloneDepInsertAfterSFP 6 Like A2, but additionally makes new object depend on the old one.
E8 ObjectCloneDepInsertAfterSRFP 10 Like A4, but additionally makes new object depend on the old one.
E9 ObjectCloneDepInsertAfterSAFP 10 Like A6, but additionally makes new object depend on the old one.
EA ObjectCloneDepInsertBeforeSP 4 Like 9A, but additionally makes new object depend on the old one.
EB DeleteAllDependingObjects 1 Delete all depending objects, but only if 'this' has no parent
EC
ED ObjectMoveRelative( u16 AnimationID, s16 X, s16 Y) 6
EE ObjectMoveWaitRelative( u8 ) 2
EF