Tool: PokéScript

[esperance]

PokéScript

PokéScript, much like older programs of a similar name, is a script editor for the third generation Pokémon games. Created partially as an attempt to better understand the scripting engine and partially out of an annoyance with, PokéScript combines the features other programs but rather than following the accepted format, PokéScript changes up the fundamental layout of the script in an attempt to better parallel the capabilities of the scripting bytecode.

Features

• New scripting style. While it features a familiar style, PokéScript treats everything from a command to text as part of a single block. This is a step away from the "#org" focused scripting style and allows for more fluid scripts.
• Unfriendly decompilation. Unlike other editors which will hide basic script commands via macro commands such as "msgbox" when decompiling, PokéScript does no such thing. Instead, features like macros are a compile-only feature. When you decompile a script, you see it exactly as it is in the ROM. I would argue this is a bonus, as you can see exactly what makes up a script.
• Colorful UI. See for yourself below. The editor features colorful syntax highlighting and even a few helpful pop-ups (colors are a bit... bright right now and will probably change by the release).
• Useful directives that allow creation of custom macros and even game-specific code!
• Editable command names. Unlike other script editors, you are free to change the names of any commands as you like. Due to a current limitation in the coding command parameters cannot be modified.
• (planned) Cross-platform. The current version is written with Windows-specific use in mind. However, there is a working version of a more XSE-like compiler written in the D language which shows promise as a platform independent compiler.

Screens

Spoiler:

A sample script, showing off the new script format.

That same script, decompiled. PokéScript does not hold your hand when editing decompiled scripts.

Downloads

Coming soon!

Source Code

Source code is available on Github. Follow development as I get closer to a release!

Worried About Learning?

Experienced scripters worry not, as command names are mostly the same as those used by PKSV. For those new to scripting, if the project gains enough interest (in continued development) I would love to create a comprehensive tutorial for scripting with the new PokéScript.

Want to Help?

I am not in need of any help with the actual programming of the tool. The project code as quickly grown large enough that I doubt anyone would want to wade through it.

However, the first release will be a beta and I need as much feedback as possible! I need people that are willing to write scripts and tell me about any bugs they encounter (hopefully none), thoughts on how the program feels, etc.

 

[Joexv]

Something that annoyed me with current scripting platforms is the ease to overwrite things in your ROM. Would it be possible to add in a size check for the scripts to prevent this? Even a simple popup that says "Hey idiot you should probably repoint this" would be plenty.

 

[Rabbles the BInx]

I know nothing about scripting for Pokémon hacks, but I do have some basic knowledge of scripting for another program. I like how easy to read and understand the code you're using is, looks like something I could pretty easily pick up. I dunno, maybe they all are this clean, but I like it. Looking forward to seeing what this can do.

 

[chrunch]

Does it have support for legacy scripting languages? Not interested in relearning all the commands and syntax for what, fancy coloured scripts? And the "Unfriendly Decompilation" sounds like a waste of time, I actually want to be able to easily understand what my decompiled scripts are doing. Why would anyone want to switch to this when XSE is much more feature complete and user friendly?

 

[NewDenverCity]

In response to what crunch said, I think that we should have an option for things in the future. I would like to have my scripts decompiled the way you have it currently, but it could be useful for other people to have it crunch's way.

 

[esperance]

Something that annoyed me with current scripting platforms is the ease to overwrite things in your ROM. Would it be possible to add in a size check for the scripts to prevent this? Even a simple popup that says "Hey idiot you should probably repoint this" would be plenty.

It probably wouldn't be that hard to add such a feature. However, I think it is more important to stress the importance of dynamic versus static offsets. When you use a specific static offset, you should be aware that you are telling the compiler to ignore freespace finding and write directly to that offset.

Here's what I'm thinking: instead of checking whether you're going to overwrite too much during an actual compile, a size checker could be implemented for the debug ("test") compilation instead. If you want to make sure the script will work correctly, you'll do a debug compile which doesn't write the script to the ROM but instead will check to make sure you're writing safely.

Does it have support for legacy scripting languages? Not interested in relearning all the commands and syntax for what, fancy coloured scripts? And the "Unfriendly Decompilation" sounds like a waste of time, I actually want to be able to easily understand what my decompiled scripts are doing. Why would anyone want to switch to this when XSE is much more feature complete and user friendly?

To answer the question of why not XSE: XSE is outdated and has a number of incorrect or poorly named commands, which this version should not. Better yet, it's open source to allow people to actually continue to improve the program years from now and fix any bugs.

I'm of the opinion that decompiling the script into macros is unnecessary, but like Team Fail said this is still in development and I do plan to add that capability in the future as I can understand why people would want it.

Finally, I think you're misunderstanding the level of change in the syntax and commands. First, command names are not that different from PKSV/XSE and they're quite easy to change if you're unhappy with the names I've chosen. In the first release, I'll include a "new commands" file and "XSE commands" file so that you're not forced to learn the new names if you don't want to. Second, the new syntax is quite familiar, and if you're even the least bit familiar with ASM you'll find this quite easy to use. Here's a comparison of the same script in XSE and this:

// XSE version
#dynamic 0x800000

#org @start
lock
faceplayer
msgbox @m1 MSG_KEEPOPEN
release
end

#org @m1
= Hello.

// PokéScript version
#dynamic 0x800000
#include std.pks

start:
lock
faceplayer
msgbox m1 MSG_KEEPOPEN
release
end

m1:
= Hello.

There are a few obvious differences, but the scripts are still mostly the same. The most obvious difference is that labels are no longer declare with "#org"/"#seek" but rather just like you would in ASM via a name followed by a colon, and they do not require an @ character. The other main difference is that the "standard library" is not included by default. Another change is that directives can start with either a '#' or a '.' unlike XSE which only allows a '#'.

To demonstrate why I find my proposed script format superior, I'll show you a script that cannot be done with XSE the way it is:

#dynamic 0x800000
#include std.pks

start:
lock
faceplayer
checkflag 0x200
jumpif TRUE next
msgbox m1 MSG_KEEPOPEN
givepokemon PKMN_PIKACHU 5 ITEM_ORANBERRY 0 0 0
setflag 0x200

next:
msgbox m2 MSG_KEEPOPEN
release
end

m1:
= Here's a PIKACHU.

m2:
= Take care of PIKACHU for me!

The script in XSE would look something like this:

#dynamic 0x800000
#include stdpoke.rbh
#include stditems.rbh

#org @start
lock
faceplayer
checkflag 0x200
if 1 goto @next // admittedly, XSE handles if commands better at this time
msgbox @m1 MSG_KEEPOPEN
givepokemon PKMN_PIKACHU 5 ITEM_ORANBERRY 0 0 0
setflag 0x200
// XSE does not insert script parts linearly, and does not recognize that we want @next added to the end
// thus we need to include a goto command or add a copy of next here
goto @next

#org @next
msgbox @m2 MSG_KEEPOPEN
release
end

#org @m1
= Here's a PIKACHU.

#org @m2
= Take care of PIKACHU for me!

If you want to see more of how it works, I've included a few sample scripts on the github and I will add more as development continues.
Samples
For example, how a script can be written to not only call some ASM but also insert it at a dynamic offset by including the ASM binary in the script with the '#includebinary' directive:
#includebinary

Also, development update: I finished support for braille yesterday. At this point the program should be able to compile/decompile any script in the ROM.

 

[pokedude9]

Good one!

There is just one major problem that every script-editor programmer keeps doing and doing again and that is hardcoding the arguments. You could just simply create an XML file containing all the commands and macroes (I've done that, it's a pain in the arse), reading them dynamically and searching for the correct command by identifier byte. It requires a bit of work, but gives the possibility of extending the XML file easily and creating new command and macroes!

Good luck with your project!

 

[azurile13]

YES. Decompiling is infuriating when script editors give back stuff like the "checkflag POKEDEX" in your example and changes them into macros. 99% of the time, I just want the hex value and having to go through extra steps is a pointless pain. I don't mind the script format since I find it easier to compile my scripts with a thumb assembler anyways, so my scripts look like that to begin with. Because of this, I actually find your "unfriendly" decompilation a lot easier to read.

About the labels in the decompiler - would it be possible to have some feature where double clicking on a label name moves you to the actual label? I just hate scrolling up and down on long scripts with frequent calls and gotos. Perhaps I'm dreaming on this one, though :) Either way, looks nice!

 

[esperance]

Good one!

There is just one major problem that every script-editor programmer keeps doing and doing again and that is hardcoding the arguments. You could just simply create an XML file containing all the commands and macroes (I've done that, it's a pain in the arse), reading them dynamically and searching for the correct command by identifier byte. It requires a bit of work, but gives the possibility of extending the XML file easily and creating new command and macroes!

Good luck with your project!

Thanks! Yeah, at the moment the arguments are hardcoded because of the trainerbattle command, which has a variable number of arguments unlike any other command as far as I am aware. I originally had the command arguments dynamically read but this exception led me to hardcode until I could figure out a suitable solution.

And macros are already easily defined by the user. In fact, every macro is saved in the standard library and can be edited. For example, the msgbox macro is defined in std.pks as:

.macro msgbox a b
	loadptr 0 a
	stdcall b
.endmacro

YES. Decompiling is infuriating when script editors give back stuff like the "checkflag POKEDEX" in your example and changes them into macros. 99% of the time, I just want the hex value and having to go through extra steps is a pointless pain. I don't mind the script format since I find it easier to compile my scripts with a thumb assembler anyways, so my scripts look like that to begin with. Because of this, I actually find your "unfriendly" decompilation a lot easier to read.

About the labels in the decompiler - would it be possible to have some feature where double clicking on a label name moves you to the actual label? I just hate scrolling up and down on long scripts with frequent calls and gotos. Perhaps I'm dreaming on this one, though :) Either way, looks nice!

I'm glad you think the same way I do! :)

And I'll see what I can do about the label clicking.

 

[chrunch]

Gonna be that person, but it is probably still in active development, so more user-friendly features probably have yet to be added.

Maybe, but it doesn't fill me with confidence seeing "Unfriendly Decompilation" listed as a feature of the tool.

To answer the question of why not XSE: XSE is outdated and has a number of incorrect or poorly named commands, which this version should not. Better yet, it's open source to allow people to actually continue to improve the program years from now and fix any bugs.

XSE is also open source but everyone seems to gloss over that fact. It's amusing seeing how fixated certain members of this community are on open source, yet they ignore actual open source programs out there in favour of their own.

And I don't see the problem with having to use goto every now and then. I don't think it's as big of a deal as you make it out to be.

 

[esperance]

XSE is also open source but everyone seems to gloss over that fact. It's amusing seeing how fixated certain members of this community are on open source, yet they ignore actual open source programs out there in favour of their own.

And I don't see the problem with having to use goto every now and then. I don't think it's as big of a deal as you make it out to be.

To be fair, even if XSE is open source it's written in VB6, an arguably outdated language that has no place being used for a modern Windows 8/10 program.

 

[chrunch]

To be fair, even if XSE is open source it's written in VB6, an arguably outdated language that has no place being used for a modern Windows 8/10 program.

So not only does the tool have to be open source, but it also has to be specifically written in the language of your preference? What happens if in several years your tool is also considered outdated, or the hackers of the future dislike your language of choice? Does the cycle just repeat endlessly?

 

[pokedude9]

This discussion personally makes me rage. Both of you make valid points, but this needs to be split up into two points of view: The programmer's and the user's view.

User's view:
"We've always worked with XSE, accepted it's flaws, bypassed its limitations and learned about which of the commands are erroneous and how to bypass that. We would like to have a less buggy editor, but it should be exactly like XSE so we don't have to learn the GUI (and maybe the language) over and over again."

Programmer's view:
"VB6 is a highly outdated and native language which was only made for the windows operating system. We need to have some cross-platform tools to have a bigger audience and this requires the use of a language that's mostly system-independent. XSE wasn't extensible, had flaws concerning commands and didn't provide enough useful features for managing scripts."

Everything will be once outdated, but your goal should be to program your tool in a way in which it serves the user for quite long. VB6 and .NET Mono is definitely the wrong approach here, chrunch. XSE needs to be improved, but not in the VB6 language, lol.

And as for you, Lost, writing programs for windows-only outside of business is the most ignorant thing I've ever heard. I know quite a lot users here who use a unix-based system or OSX, what about them? If you really want to fully go cross-platform, without code modifications and at the highest performance at the same time, you need to use a language like C++ and a framework like Qt. "I do not want to learn C++ (or any other language)" is not an excuse. Take diego as a role-model here!

Oh and before I forget, you should give credits to Pavel Torgashov for his marvellous syntax-highlighting editor!

 

[esperance]

So not only does the tool have to be open source, but it also has to be specifically written in the language of your preference? What happens if in several years your tool is also considered outdated, or the hackers of the future dislike your language of choice? Does the cycle just repeat endlessly?

If they dislike the language I've chosen then they're free to write their own version in whichever language they like. I wrote my own version in C# not because I couldn't modify XSE's source but rather because I did not want to. Consider this an instance of constructive discontent. I was not satisfied with current programs, so I wrote my own. If someone feels the same, they're free to do so as well.

And as for you, Lost, writing programs for windows-only outside of business is the most ignorant thing I've ever heard. I know quite a lot users here who use a unix-based system or OSX, what about them? If you really want to fully go cross-platform, without code modifications and at the highest performance at the same time, you need to use a language like C++ and a framework like Qt. "I do not want to learn C++ (or any other language)" is not an excuse. Take diego as a role-model here!

Oh and before I forget, you should give credits to Pavel Torgashov for his marvellous syntax-highlighting editor!

I'll ignore the fact that this is a hobby program and answer your point anyway: I've already stated in the OP that I have a working version written in the D language (which I wrote on a Mac anyway) so your concern is misplaced.

I wrote the main version of the program in C# because I am most familiar with the language and having a working version in a Windows-specific environment goes a long way already as from a market share perspective I have a version that works with 90% of computers anyway.

And very good point. I got my syntax highlighting editor from Pavel Torgashov.

 

[pokedude9]

I'll ignore the fact that this is a hobby program and answer your point anyway: I've already stated in the OP that I have a working version written in the D language (which I wrote on a Mac anyway) so your concern is misplaced.

I saw that, but it does not offer a GUI functionality. That's what I primarily wanted to point out!

I wrote the main version of the program in C# because I am most familiar with the language and having a working version in a Windows-specific environment goes a long way already as from a market share perspective I have a version that works with 90% of computers anyway.

But see it this way: There also are other devices apart from computers, like mobile phones. None of your code will run on those.
Let's not discuss this any longer. Good luck with your tool!

 

[DJTiki]

But see it this way: There also are other devices apart from computers, like mobile phones. None of your code will run on those.

I haven't hacked in months, but even I know that no one would be audacious as to try and hack on a mobile device.

No offense. There are too many programs and too much data in the Pokemon ROMs for that to be a possibility without writing entirely new programs to replace G3HS, G3S, the map editors (especially the DS compatible), and the sheer amount of hexadecimal values and ASM compiling you'd have to work with. In other words, I don't see the problem for a hobby program to be written in C# and D.

EDIT: I know there's the "Mobile ROM Hacking is possible if we believe!" Newbies don't have the patience to fiddle with their phone to edit a map or compile a script. I know I don't.

 

[Radix]

So not only does the tool have to be open source, but it also has to be specifically written in the language of your preference? What happens if in several years your tool is also considered outdated, or the hackers of the future dislike your language of choice? Does the cycle just repeat endlessly?

Not really. VB6 was phased out a long time ago. A lot of previously high-impact languages that had rather obscure specifications (e.g. COBOL, ALGOL, Delphi, Pascal, and more recently, VB6 itself) have fallen out of mainstream use in deference to languages that express things in more standard forms. These languages fall mainly into three categories; dynamic, systems, and functional, delineated by Javascript/Python, C and its variants (e.g. D, Rust, C++), and Haskell, respectively.

Pre-.NET VB was developed strictly in the 90s, back when we still had no idea what the chuck we were doing. It's 2016 now, and we've mostly figured out how to do things correctly, characterized by a general progression towards memory-safe (Rust/Go) and functional designs (e.g. cambrian explosion of FRP [1] [2] [3] [4], Haskell gaining popularity, lambdas introduced in C++11, Java 8).

VB6 is one of those old languages based off of the BASIC syntax. I've ported VB6 code before, and it was a nightmare. Like trying to port a PHP/SQL stack over to node/mongo. Absolutely terrifying.

Just to stretch the analogy a bit, how would you react if XSE was written in BF? I dearly hope you wouldn't force someone to port that.

In terms of desktop applications, the situation is hazy and there isn't really a best way to go. The better choices for now are Qt, Gtk, and Electron, despite their respective flaws. And if you really want to make non-Windows users' lives miserable, C# is an okay choice. Personally, I use Electron for most things.

 

[pokedude9]

Why would I be hating on a language I've used for several years, almost a decade myself? I just don't get why so many people go huge detours just because they don't want to learn a certain language/framework!