Scripting is what coordinates and executes in-game events to create a story for the player. Gen III hacks have been able to tell new stories with custom scripts written from scratch; future hacks in more current generations are key for good hacks. This thread is to provide information in regards to how to script, what script commands do, and some example scripts. I'll try to go more in depth than pichu2001 did in his basic tutorial thread; if you are just starting off scripting, you should definitely read his thread first.

First you need to extract the Script .narc with NitroExplorer, and unpack it into the individual files with editor.exe (kiwi.ds).

• Program & Lua starter kit: download here
• The location of the scripts is /a/0/5/6

There is currently no XSE equivalent of symbolic scripting for B2W2. We're doing this with hex. So have a hex editor ready (HxD or Hex Workshop), and get PPNFR to replace the individual scripts you edit.

How do you know what script is used where? You currently need to use a Lua script while emulating. The script depicted below is in the starter kit.

At the bottom right corner of the touch-screen, it tells you which Script is being used. Correlate this with the file numbers you extracted from the narc.

As previously described by pichu2001, the script contains two parts. The pointers and the scripts that are pointed to.

Pointers are 4 bytes long (32 bits); the first script in this example image points to 00 00 00 38, which is equivalent to 00000038 = 0x38. 0x38 bytes after this pointer is the start of script 1. Use this formula to find the script's location in the file:

Current Read Offset + Pointer Value = Script Offset

In this example image, 0x04+0x38 = 0x3C. The first script is located at 0x3C... unfortunately it starts off reading as "End", so the script ends there. Try finding the offset of Script 2; you should get 0x3E, which just so happens to start right after Script 1 ends.

To tell the game to stop reading pointers, a 16 byte "STOP" = 13 FD is used (0xFD13). After the STOP, there are no more pointers and the raw script command data starts. Pointers are an important part of the file; if you insert anything between existing data, the pointers will point to improper locations. I'll cover this later.

Knowing how to script requires you to observe how commands are normally used by others. I'll show you an example script that has an NPC says a text line and ends the script when dismissed.



Above is the example script file. As you can see, it contains one script, which starts at 0x06.

Code:

---

02 00 00 00 13 FD 2E 00 A6 00 47 05 74 00 3D 00 00 04 0A 00 00 00 00 00 32 00 3F 00 30 00 2F 00 02 00 00 00

---

First we must separate out our script data. Remove everything before the start of our script (everything before 0x06)

Code:

---

2E 00 A6 00 47 05 74 00 3D 00 00 04 0A 00 00 00 00 00 32 00 3F 00 30 00 2F 00 02 00 00 00

---

Looks decent, let's make this more easily to see:

Code:

---

2E 00                                -- LockAll
A6 00 47 05                        -- PlaySound Clink
74 00                                -- FacePlayer
3D 00 00 04 0A 00 00 00 00 00        -- Message2, text line 0xA, default settings
32 00                                -- WaitKeypress
3F 00                                -- CloseMessage2
30 00                                -- WaitDelay
2F 00                                -- UnlockAll
02 00                                -- End

00 00                                -- Padding to make the file's size divisible by 0x4

---

This is gibberish to the untrained eye, so I'll explain what each line does in 'English'.

Code:

---

LockAll        0x002E                -- Stop all movements of NPCs and Player. LOCK EVERYTHING.
PlaySound Clink        0x00A6 0x0547        -- Play a sound, sound number 0x0547 - "clink"
FacePlayer        0x0074                -- Make the NPC that was interacted with face the player

Message2        0x003D                -- Pops up a speech bubble from the interacted with NPC
                0x0400                -- Tells the game to use the current text file
                0x000A                -- Tells the game to use text line 0xA
                0x0000                -- Tells the game to place the bubble away from interaction
                0x0000                -- Tells the game to use the default speech bubble

WaitKeypress        0x0032                -- Wait until a button is pressed before proceeding
CloseMessage2        0x003F                -- Close the popped up speech bubble

WaitDelay        0x0030                -- Waits a frame; cools down the game
UnlockAll        0x002F                -- Allow all NPCs and player to move
End                0x0002                -- Ends the script; read no further!

---

Pretty easy to interpret when you know what each command is...

The game likes to keep track of what has happened in game, and your choices that you have made.

• If you get an item from an NPC, the game sets a flag so that the NPC doesn't give it out again.
  • The game also sets flags to prevent NPCs from spawning (so that progress based NPCs appear/disappear)
• If you choose a certain starter, the game sets a Const container to know what Rival teams to face you against.
  • Constants are stored in the save file along with flags.
• Variables are temporary values that are used to contain values for a short time.
  • Variables do the majority of the work in scripts. They are defined by some command, then later used as dynamic parameters. Essentially symbolic math.
  • Variables are not saved in the save file; however if they are not cleared/set properly their values can persist into other custom scripts. When you are done with them, clear them!

This introduction to scripting is just touching the surface on what you can do with B2W2 scripting. With over 800 commands at your disposal (more than 3x that of Gen III), there's so much more you can do!