Pokemon Black: Scripting Lessons(I try...)

[pichu2001]

Foreground

Hi, people!
I see you're latest trying to figure how scripts works on BW, and I wanna give my contribution.
Really, I've started about two years ago editing BW scripts, for a future addition on PPRE, but nothing happened later and my work remained hidden for a lot.
I wanna share with you my knowledge about scripts, so let's go!
(This tutorial presume that you know something about hex and programmation)

Script Structure

In a BW file, like DPP and HGSS, the scripts can divided in two main sections: declarative and command section.

Declarative Sections

Declarative part contains all "offset" of the scripts (start offset in particular). The
Each offset is saved in a UInt32 (4 byte), and we must add the "actual" reader position for reach the real script start. This section end ever with 0x13FD.
Example:

  0A 00 00 00 08 00 00 00 FD 00 00 00 13 FD

This is a declarative part for a/0/5/7-0, containing 3 scripts.
1st offset script: 0x0A + 0x04 = 0x0E
2nd offset script: 0x08 + 0x08 = 0x10
3rd offset script: 0xFD + 0x0A = 0x107

Command Sections

Command section contains the real commands that will be executed by scripts.
There are 800+ different command, but the main structure is

0x0 -0x4 ID Command
[Various parameter]

Next lesson, we can see some simple script in action.
Stay tuned.

[X-Lan]

This could be really handy series. Nice work! xD

[pichu2001]

Thanks for support...

Lesson 1: Simple Message Script

Starting with something of simple: we wanna a overworld tell us a simple message, like "Hello, world!".
So, after we have opening our file to edit, go to offset of the our script (Lesson 0 - Declarative Part) and start writing. (I'll use red color for command and blue for parameters)
So, the first command we need to insert is:

002E 

This command rapresent the beginning of the script.
It haven't any parameters. We'll call StartScript .
After, maybe we wanna to "hear" the famous 'click' when we talking with a person. So our script became:

StartScript 
A600 4705

This new command playing a generic sound, in this case 4705, that rapresent 'click'. If you want another sound, you can change the parameter. We will call PlaySound .

Now we wanna talk with well-mannered person, so we wanna that he/she face us while he's talking.
We'll use:

StartScript 
PlaySound CLICK
7400 

This command forced people to face the player. We'll call in fact FacePlayer .

Now the message:

StartScript 
PlaySound CLICK
FacePlayer 
3D00 0004 0000 0000 0000

The message is a little more complex. There are a lot of different command for showing a message, but this is the simplest. Now we analized each parameter.

• 0004 : Costant.
  We ever need to insert it.
• 0000 : Message Id.
  Differently from GBA games, we needn't to insert the offset of message.
  In fact each map is linked with a file of Msg.Narc ( a/0/0/3) that contains an ordered sequence of "messages". So the parameter tell us that the message is the 0x0 message in linked msg-file.
  (Later I give you all the association script-message file, I promise)
• 0000 : Top/Bottom View.
  Indicate where the message is show on the screen. (0000 = Bottom, 0001 = Top)
• 0000 : Type of Border.
  Indicate which type of border has the messages. (0000 = Simple)

Now we have finally insert message, but we need other commands to close the script.
First:

StartScript 
PlaySound CLICK
FacePlayer 
Message MSGCONST ID=0 BOTTOM NORMAL
3200 

This command forced the message to remain open until you click a botton.
We'll call WaitButton.

StartScript 
PlaySound CLICK
FacePlayer 
Message MSGCONST ID=0 BOTTOM NORMAL
WaitButton 
3E00

This command close the message. We'll call CloseMessage.

StartScript 
PlaySound CLICK
FacePlayer 
Message MSGCONST ID=0 BOTTOM NORMAL
WaitButton 
CloseMessage
3000

I don't know really what this command do. But you need to insert after a CloseMessage.

StartScript 
PlaySound CLICK
FacePlayer 
Message MSGCONST ID=0 BOTTOM NORMAL
WaitButton 
CloseMessage
3000
2F00

This command closing the script. We'll call EndScript.

Latest command is the 0200 command, that is the End of all routine.
So we have this sequence's of command to insert into our HexViewer:

2E00 A600 4705 7400 3D00 0004 0000 0000 0000 3200 3E00 3000 2F00 0200

The "human-friendly" version of the script is:

StartScript 
PlaySound CLICK
FacePlayer 
Message MSGCONST ID=0 BOTTOM NORMAL
WaitButton 
CloseMessage
3000
EndScript
End

This is all for now. I hope I was clear.
Stay tuned for next lessons...

pichu2000

[Poryhack]

Excellent stuff, keep the lessons coming!

[tybantarnusa]

What a nice lesson.
So, that's how the script works.

Really easy to understand.

[pichu2001]

Thanks a lot, I'm very happy that it's simple to understand....
Now another lessons for you, people!

Lesson 2: Simple Message Script with variations.

There are a lot of different messages command, that give us a very powerful way to tell something.
Now we start analyze.

003D

We already use this command, but now we give a deeply look into.
The last parameter, that we called NORMAL, can be changed to give another whole aspect to the box.
Here there's a list of values that we can use:

• 0000 : NORMAL.
• 0001 : ANGRY.

003C

This command has a similar sintax of Message, although there is a new parameter, called NPCID, that rapresent the person from which depart the "arrow" of the message.
We'll call DirectedMessage .
The signature of command is:

DirectedMessage MSGCONST ID=0 NPCID BOTTOM NORMAL

We can use this command when we want that another people speak during script.

0034

This command is more simple than the other two.
It show a message into a grey box, used mostly when you received an item.
We'll call EventGreyMessage.
The signature of command is:

EventGreyMessage MSGID  BOTTOM

Important: To close this message, we need to use 0036 command, instead of CloseMessage.
We'll call this last command CloseEventMessage.

0038

It show a message without arrow, used mostly when we don't know who's speaking.
We'll call BubbleMessage.
The signature of command is:

BubbleMessage MSGID  BOTTOM

Important: To close this message, we need to use 0039 command, instead of CloseMessage.
We'll call this last command CloseBubbleMessage.

003A

With this command, we show a bubblemessage at specified coordinates.
We'll call ShowMessageAt.
The signature of command is:

ShowMessageAt MSGID X Y

Note: The (0,0) position is on left upper angle of screen.

0043

It show a message with a coloured border, used mostly when we read city's signs or target.
We'll call BorderedMessage.
The signature of command is:

BorderedMessage MSGID COLOR

The color values are:

• 0000 : PINK.
• 0001 : BROWN.
• 0002 : BLUE.
• 0003 : GREEN.

Important: To close this message, we need to use 0044 command, instead of CloseMessage.
We'll call this last command CloseBorderedMessage.

0045

It show a strange transparent message, like a destroyed paper.
We'll call PaperMessage.
The signature of command is:

BubbleMessage MSGID  X

This command need't some little study research.

Important: To close this message, we need to use 0046 command, instead of CloseMessage.
We'll call this last command ClosePaperMessage.

0048

This command is equal at DirectedMessage.
The only difference is an other last parameter, that is always 0.
We don't use it, for now.

0049

This command is similar at DirectedMessage, but with an important differences: the message change if we are playing Black or White.
So we'll call DoubleMessage

The signature of command is:

DoubleMessage MSGCONST MSGIDBLACK MSGIDWHITE NPCID BOTTOM NORMAL

004A

It show an angry Message, when we want that the people "shout",
We'll call AngryMessage.
The signature of command is:

AngryMessage MSGID  BOTTOM

Important: To close this message, we need to use 004B command, instead of CloseMessage.
We'll call this last command CloseAngryMessage.

All of this command we can use in our simple script, remembering to close messages with right command.
Today's lesson finish here.
The next time we'll see messages contains variables (Like Hiro's name and other type)
Stay tuned!

pichu2000

[X-Lan]

You make things so much easier to understand. I only know a handful of stuff like pokemon, type & move editing (the basics on HxD) but where/how do i find the message lines so i dont mess with the wrong stuff? How do i edit the narc files text?

I would be grateful if you let me know some of the locations, either here or via pm :P

Btw!

0034

This command is more simple than the other two.
It show a message into a grey box, used mostly when you received an item.
We'll call EventGreyMessage.
The signature of command is:

Code:

EventGreyMessage MSGID BOTTOM

Important: To close this message, we need to use 0036 command, instead of CloseMessage.
We'll call this last command CloseEventMessage.

0034

This command is more simple than the other two.
It show a message into a grey box, used mostly when you received an item.
We'll call EventGreyMessage.
The signature of command is:

Code:

EventGreyMessage MSGID BOTTOM

Important: To close this message, we need to use 0035 command, instead of CloseMessage.
We'll call this last command CloseEventMessage.

Whats the difference between the 2, than the 'CloseEventMessage' command 0036 & 0035?

[pichu2001]

Sorry, I adjust it.
It's a duplication of text, my mistake.
For messages you can use PPTXT (In this forum), for association (script --> messages) , you had to wait a little.
I make an association table soon, I promise.
(Preview: Nuvema Town has a057/778 as script, a003/428 as message.)

[Flintiex]

Thank you! These tutorials are great! Keep em coming Hopefully there'll be a PPRE for gen 5 which would have a script editor for B/W soon..

[Drayano]

Bump because this is a useful thread.

I noticed an issue with the first post...

This is a declarative part for a/0/5/7-0, containing 3 scripts.
1st offset script: 0x0A + 0x04 = 0x0E
2nd offset script: 0x08 + 0x08 = 0x10
3rd offset script: 0xFD + 0x0A = 0x107

I'm fairly sure the 3rd offset is 0xFD + 0x0C, rather than 0x0A. It goes up in a sequence of 4s each time, so +4, +8, +C, +10, +14, +18, +1C... etcetera.

I gave this a whirl on BW2 and got some success! The possibilities are exciting me, heh. But there's still some crucial commands that I need to find the codes for, such as 'Setflag', 'Clearflag' and such.

[Kaphotics]

The best way to figure out script command codes is by finding an area with as little scripts as possible; find the NPC that uses said script and try to identify what the overall purpose of the script is. Then you figure out the overall structure based on known commands, then find the areas that are unknown...

By fiddling with them a bit in the RAM, you can see how they break the script if changed. Take a piece of the script (32 bits) and search it with DeSmuME after you've made the game use one script on the currently loaded map. (The game doesn't load the script file for a given location unless a script is called for that location!)

I suggest looking at an NPC that trades, and says certain lines based on if the trade was completed or not.

[Drayano]

Yeah, that sounds good. Thankfully there's a lot of buildings with only one or two people inside, so it's not too hard to zone in on things.

...I should probably learn how to tinker with RAM, haha.

I think there's a few commands I've figured out;

"70 01 XX XX YY 00" seems to be the regular Wild Battle script, although if used by itself the game freezes after the fight, so I assume you need something else to stop that from happening. I managed to copy the Volcarona script into another area and that seems to be working okay...

"93 02 XX XX YY 00" is a weird one; it's another wild encounter script but what it actually does seems to change depending on what's around it. You see it used both in the shiny Haxorus script and for the Black/White Kyurem fight. I can't seem to figure out what it actually does by itself, heh. Experimentation has also found it to cause the battle pads to be different. Really, really strange.

"23 00" is the setflag command I think.

Btw, can't thank you enough for the lua script. Definitely made things so much easier.

(Note to self: the game doesn't seem to like all values of flags up to 65535 even though there are two bytes. Numbers about 3000 and below seem to be fine, though.)

[Kaphotics]

Nice

Back when I ripped the stationary encounter data, it was all from scripts; I just searched the "wild battle" script command after I figured out what it was in B2W2.

As for the other flag commands, they'd probably be adjacent to the setflag, and in the <0x0030 range. If it's any confirmation, 1E/1F/20 handled flags in DPPt.

[Drayano]

Haha, yeah, I guess stationary encounters are pretty easy to find. I'm not surprised you figured that one out easy.

Okay, seems you're right. I can confirm the clearflag command is "24 00 XX XX". Though it doesn't seem to support all numbers up to 65535; a lot of numbers past 3000+ won't allow the flag for it to be set in the first place. I dunno if I'm just messing something up or if the game outright won't let me do it, though.

I also found one more interesting script - the key unlocker!

The code is AC 02 XX XX, where XX XX is the value of the key. I found these:

00 - ?? (Assist Mode?)
01 - Challenge Mode
02 - ??? (Rock Peak Room?) 
03 - Iron Room
04 - Glacier Room
05 - Assist Mode (Purple Key??)
06 - Challenge Mode (Purple Key??)
07 - Purple Key?
08 - Purple Key?
09 - Purple Key?

When I say purple key, I had some values with a messed up colour key. For example, the challenge mode ones:



Purple one left, regular one right. I suspect it's just an invalid key or something. I didn't find the values for the Black Tower / White Treehollow but they'd probably be pretty easy to find.

So I guess unlocking Assist/Challenge Mode off the bat should be easy enough. :3

edit: I /think/ the Checkflag is "10 00 XX XX", though I don't know how to actually use it.

[aninymouse]

Ohoho... that is just perfect ♥ Thanks for finding this out!

Have you tested it to see if it permanently unlocks challenge/assist in this way?