Well, I definitely wished I could have released the new version of VWF Dialogues Patch during this C3, but I'm a notoriously slow worker, and I kept pushing the this version's scope higher and higher, like the complete fucking moron I am, to the point where I basically reworte like half the thing*, so alas, just a preview it is for today.
* Major exaggeration.
I started picking up work on VWF Dialogues Patch again for two main reasons. One reason was to fix bugs and incompatibilities. Some of you might remember that yoshifanatic, who really contributed most of the new features for v1.3, already submitted it to this site a few years back. However, it was rejected/pulled again, due to having some incompatibilities (it either didn't work on hardware, or didn't work in newest emulators, depending on settings). Since the patch was lying dormant on my GitHub for years, I decided to finally tackle these bugs. The second reason was that the version of the patch currently hosted on SMWC doesn't actually assemble in the newest version of Asar, and it's mostly my fault for creating the function hell that is shared.asm, so I wanted to change that.
However, once I started working on the fucking thing, I immediately noticed how full of shit it was. Understandable, considering I made it almost 15 years ago. I immediately noticed potential for major improvements, especially utilizing features of upcoming Asar version 1.9, so I got to work and immediately turned what would have otherwise been a multi-week project into a multi-month one. Honestly, I'm really fucking surprised I haven't lost moviation yet - so rare for me nowadays - but I actually got to a point close to completion, and everything that's left now is some remaining testing, bug fixing (mostly on hardware) and polsihing. So without further ado, here's a sneak peek at some of the new features you can look forward to.
Greatly Improved Usability
Take a look at this:
What you see here is your average message when using VWF Dialogues Patch v1.2. Now take a look at this:
This is that exact same message, but rewritten for VWF Dialogues Patch v1.3.
The entire patch has been rewritten so that you can now write messages entirely using Asar macros and function. As a result, you no longer have to memorize any magical hex numbers and messages immediately become 300% more readable (well, in theory - some of the new macro names are kinda annoyingly long, which does take away a bit from readability, but I plan to improve this even further by adding abbreviations for all macros later on). As an added bonus, these macros automatically do 99% of all the distinctions that you need to for the patch's 8-bit and 16-bit modes. Another nice bonus is that these macros do a lot of error-checking at build-time, so for a lot of errors, you no longer have to start your ROM, only to find out that it'll break in horrible ways.
Probably the biggest improvement is the %vwf_header() macro. It uses a new feature of Asar v1.9, varidadic macros, which basically lets you define macros with optional arguments. One of the nastiest thing of older VWF versions was that you always had to specify the entire header for each message. Not only was this quite annoying, but it was also horrible to memorize, because the old header format was just a bunch of magic bits and bytes again. Also, if you wanted to change the default look of all your text boxes, you would have previously had to edit every single message header. That's no longer the case. Now, you simply provide defaults for every single header setting, and you can skip specifying any of them. You only need to specify the settings you want to change for a given message, which looks like this:
Again, I'll likely touch up the formatting a bit later and potentially shorten some of these names, but even in its current form, I hope you can already see the improvements over having just magic numbers.
In theory, this could even be used in a future version of the patch to reduce the overall size of the assembled patch, by skipping these default settings in the actual ROM. Currently, they are only skipped in code, but still assembled to the ROM for every header.
Skip Messages
This feature was entirely implemented by yoshifanatic, I really only fixed a minor bug with it. You can now specify a skip location for all messages. Pressing the Start button will then immediately make the text box jump to that location. Most of the time, this will simply be the end of the text box and will allow you to cancel out of any optional text boxes a random NPC might give you. Super useful if you accidentally talk to an NPC when you didn't want to.
Automatic Pointer Generation
The old version of the patch used a file called vwfmessagepointers.asm with pointers to every single message. This was not only prone for errors (in fact, the old file already contained a couple of bugs built-in), but also required manual labor if you ever wanted more than 256 messages in your hack. Well, all of that is history now, as this file is no longer needed in VWF Dialogues Patch v1.3, which automatically generates all the pointers for you, based on which messages you have actually defined.
Error Messages
Using the patch in certain ways will automatically display an in-game error message as of version 1.3. For example, trying to display an error message that wasn't filled in.
yoshifanatic originally implemented this feature, but I made it more reliable and added new types of error messages. This way, hopefully a play tester can immediately tell a hack author about any text box-related bugs they come across.
Message Box Animations
When you use the "load message" command, you can now decide to display the close/open animation of text boxes. Probably a feature with niche applications, but I can definitely think of a few. Deciding to re-show the open animation will also reload certain text box settings, like box frame or box pattern. See further below for an example of what this makes possible.
MessageASM
MessageASM is a feature originally implemented by yoshifanatic. I made some improvements to it. You can imagine it as the VWF Dialogues equivalent of UberASM: For every single message box, you can have a certain code routine that gets executed every frame. The applications for this are vast. For example, here I used it to animate the text color of a message box.
Or here I used it to implement text box customization - which is a feature that existed in code pretty much all the way since version 1.0 of the patch, but there was never s traight-forward way to utilize it. Even now, doing it with the patch alone still isn't quite perfect (for example, settings won't get saved to SRAM automatically), but at least this gets us a lot closer to it being an easily accessible feature (for, like, the two hacks that would actually even use it).
Text Macros & Text Macro Groups
Text macros are a powerful feature originally implemented by yoshifanatic, but I expanded them, fixed some bugs and greatly improved their usability. Put in simple terms, text macros are an easy way of saving space in your ROM, as well as effort. For example, have the name "Princess Peach" appear in a lot text boxes? Then you can now wrap it into a text macro. Instead of writing out the full name for every single usage, you now only need to call the macro, which takes up a mere three bytes of space in the ROM (instead of whatever the name would have normally rquired) and spares you the embarassing fate of accidentally misspelling Peach's name as "Princes Poach" in that one text box only.
However, the usefulness of text macros doesn't stop there. Combine them with text macro groups and their potential is immediately multiplied by one hundred. This feature allows you to wrap text macros into groups, and then allows you to index those groups by arbitrary RAM addresses. Want an example? Let's say you have an item system in your game, and a RAM address which stores the type of an item. If you now create text macros for the names of all items, you can wrap them into a text macro group and then index that group by the value of that RAM address. The result will be that a text box displays the correct item name, depending on the value of the address. In theory, this even makes the creation of simple menu systems possible.
In this screenshot, I created two text macro groups: "PlayerPowerupStatus" and "CurrentPlayer". Then I created a text macro "CurrentPlayerWithPowerup", which indexes the first group with by $7E0019 and the second group by $7E0DB3. By simply calling this macro in a text box, I can now display the full name of the current character in a text box, like "Fire Luigi" in this screenshot.
Buffered Text Macro
Technically an extension of text macros, I'll list them separately, because they're more of a coding feature and not quite as useful for average users. Originally implemented by yoshifanatic and then improved by me, buffered text macros function just like regular ones, except you can construct them at run-time rather than at build time. The way this works is by adding snippets of text box commands to a global memory buffer. All you need is a length and list of a commands.
Use cases will be very limited for average end users, but one use case for advanced users can bee seen below:
Here I used buffered text macros to implement an intentionally shitty name entry screen. Now the reason it's so shitty is simply because I implemented it almost entirely via the text system itself with minimal code. The text system is of course limited, so this was the best I could do without a lot of code, but in a full hack with more custom code around it, you could indeed implement a proper Secret of Evermore-styled name entry screen using this feature.
Note that displaying text from RAM wasn't exactly impossible in previus versions of the patch, but this one supports it in more of an official manner, and it's now a lot easier to do.
What's Next?
I've been working on this version of the patch for several months already, and while I had hoped to have it released in 2021, it'll likley be a couple more months from now before an actual release will happen. My vacation ends on Monday, so my free time will be more limited by then (plus, as I said, I'm a notoriously slow worker, anyways).
Some of the work left to do includes:
Thanks for reading! And if this somehow magically ends up winning anything (don't know how likely that is for an in-progress patch), don't forget that yoshifanatic made major contributions to this version and should get a trophy as well.
Feel free to visit my website/blog - it's updated rarely, but it looks pretty cool!
* Major exaggeration.
I started picking up work on VWF Dialogues Patch again for two main reasons. One reason was to fix bugs and incompatibilities. Some of you might remember that yoshifanatic, who really contributed most of the new features for v1.3, already submitted it to this site a few years back. However, it was rejected/pulled again, due to having some incompatibilities (it either didn't work on hardware, or didn't work in newest emulators, depending on settings). Since the patch was lying dormant on my GitHub for years, I decided to finally tackle these bugs. The second reason was that the version of the patch currently hosted on SMWC doesn't actually assemble in the newest version of Asar, and it's mostly my fault for creating the function hell that is shared.asm, so I wanted to change that.
However, once I started working on the fucking thing, I immediately noticed how full of shit it was. Understandable, considering I made it almost 15 years ago. I immediately noticed potential for major improvements, especially utilizing features of upcoming Asar version 1.9, so I got to work and immediately turned what would have otherwise been a multi-week project into a multi-month one. Honestly, I'm really fucking surprised I haven't lost moviation yet - so rare for me nowadays - but I actually got to a point close to completion, and everything that's left now is some remaining testing, bug fixing (mostly on hardware) and polsihing. So without further ado, here's a sneak peek at some of the new features you can look forward to.
Greatly Improved Usability
Take a look at this:
What you see here is your average message when using VWF Dialogues Patch v1.2. Now take a look at this:
This is that exact same message, but rewritten for VWF Dialogues Patch v1.3.
The entire patch has been rewritten so that you can now write messages entirely using Asar macros and function. As a result, you no longer have to memorize any magical hex numbers and messages immediately become 300% more readable (well, in theory - some of the new macro names are kinda annoyingly long, which does take away a bit from readability, but I plan to improve this even further by adding abbreviations for all macros later on). As an added bonus, these macros automatically do 99% of all the distinctions that you need to for the patch's 8-bit and 16-bit modes. Another nice bonus is that these macros do a lot of error-checking at build-time, so for a lot of errors, you no longer have to start your ROM, only to find out that it'll break in horrible ways.
Probably the biggest improvement is the %vwf_header() macro. It uses a new feature of Asar v1.9, varidadic macros, which basically lets you define macros with optional arguments. One of the nastiest thing of older VWF versions was that you always had to specify the entire header for each message. Not only was this quite annoying, but it was also horrible to memorize, because the old header format was just a bunch of magic bits and bytes again. Also, if you wanted to change the default look of all your text boxes, you would have previously had to edit every single message header. That's no longer the case. Now, you simply provide defaults for every single header setting, and you can skip specifying any of them. You only need to specify the settings you want to change for a given message, which looks like this:
Code
%vwf_header(vwf_x_pos(1), vwf_y_pos(1), vwf_width(14), vwf_height(12), vwf_text_alignment(TextAlignment.Left))
Again, I'll likely touch up the formatting a bit later and potentially shorten some of these names, but even in its current form, I hope you can already see the improvements over having just magic numbers.
In theory, this could even be used in a future version of the patch to reduce the overall size of the assembled patch, by skipping these default settings in the actual ROM. Currently, they are only skipped in code, but still assembled to the ROM for every header.
Skip Messages
This feature was entirely implemented by yoshifanatic, I really only fixed a minor bug with it. You can now specify a skip location for all messages. Pressing the Start button will then immediately make the text box jump to that location. Most of the time, this will simply be the end of the text box and will allow you to cancel out of any optional text boxes a random NPC might give you. Super useful if you accidentally talk to an NPC when you didn't want to.
Automatic Pointer Generation
The old version of the patch used a file called vwfmessagepointers.asm with pointers to every single message. This was not only prone for errors (in fact, the old file already contained a couple of bugs built-in), but also required manual labor if you ever wanted more than 256 messages in your hack. Well, all of that is history now, as this file is no longer needed in VWF Dialogues Patch v1.3, which automatically generates all the pointers for you, based on which messages you have actually defined.
Error Messages
Using the patch in certain ways will automatically display an in-game error message as of version 1.3. For example, trying to display an error message that wasn't filled in.
yoshifanatic originally implemented this feature, but I made it more reliable and added new types of error messages. This way, hopefully a play tester can immediately tell a hack author about any text box-related bugs they come across.
Message Box Animations
When you use the "load message" command, you can now decide to display the close/open animation of text boxes. Probably a feature with niche applications, but I can definitely think of a few. Deciding to re-show the open animation will also reload certain text box settings, like box frame or box pattern. See further below for an example of what this makes possible.
MessageASM
MessageASM is a feature originally implemented by yoshifanatic. I made some improvements to it. You can imagine it as the VWF Dialogues equivalent of UberASM: For every single message box, you can have a certain code routine that gets executed every frame. The applications for this are vast. For example, here I used it to animate the text color of a message box.
Or here I used it to implement text box customization - which is a feature that existed in code pretty much all the way since version 1.0 of the patch, but there was never s traight-forward way to utilize it. Even now, doing it with the patch alone still isn't quite perfect (for example, settings won't get saved to SRAM automatically), but at least this gets us a lot closer to it being an easily accessible feature (for, like, the two hacks that would actually even use it).
Text Macros & Text Macro Groups
Text macros are a powerful feature originally implemented by yoshifanatic, but I expanded them, fixed some bugs and greatly improved their usability. Put in simple terms, text macros are an easy way of saving space in your ROM, as well as effort. For example, have the name "Princess Peach" appear in a lot text boxes? Then you can now wrap it into a text macro. Instead of writing out the full name for every single usage, you now only need to call the macro, which takes up a mere three bytes of space in the ROM (instead of whatever the name would have normally rquired) and spares you the embarassing fate of accidentally misspelling Peach's name as "Princes Poach" in that one text box only.
However, the usefulness of text macros doesn't stop there. Combine them with text macro groups and their potential is immediately multiplied by one hundred. This feature allows you to wrap text macros into groups, and then allows you to index those groups by arbitrary RAM addresses. Want an example? Let's say you have an item system in your game, and a RAM address which stores the type of an item. If you now create text macros for the names of all items, you can wrap them into a text macro group and then index that group by the value of that RAM address. The result will be that a text box displays the correct item name, depending on the value of the address. In theory, this even makes the creation of simple menu systems possible.
In this screenshot, I created two text macro groups: "PlayerPowerupStatus" and "CurrentPlayer". Then I created a text macro "CurrentPlayerWithPowerup", which indexes the first group with by $7E0019 and the second group by $7E0DB3. By simply calling this macro in a text box, I can now display the full name of the current character in a text box, like "Fire Luigi" in this screenshot.
Buffered Text Macro
Technically an extension of text macros, I'll list them separately, because they're more of a coding feature and not quite as useful for average users. Originally implemented by yoshifanatic and then improved by me, buffered text macros function just like regular ones, except you can construct them at run-time rather than at build time. The way this works is by adding snippets of text box commands to a global memory buffer. All you need is a length and list of a commands.
Use cases will be very limited for average end users, but one use case for advanced users can bee seen below:
Here I used buffered text macros to implement an intentionally shitty name entry screen. Now the reason it's so shitty is simply because I implemented it almost entirely via the text system itself with minimal code. The text system is of course limited, so this was the best I could do without a lot of code, but in a full hack with more custom code around it, you could indeed implement a proper Secret of Evermore-styled name entry screen using this feature.
Note that displaying text from RAM wasn't exactly impossible in previus versions of the patch, but this one supports it in more of an official manner, and it's now a lot easier to do.
What's Next?
I've been working on this version of the patch for several months already, and while I had hoped to have it released in 2021, it'll likley be a couple more months from now before an actual release will happen. My vacation ends on Monday, so my free time will be more limited by then (plus, as I said, I'm a notoriously slow worker, anyways).
Some of the work left to do includes:
- Fixing a few final bugs
- Testing on hardware (sd2snes)
- Improving readability by adding abbreviated commands
- Rewriting the manual (like, literally, almost the entire thing - yikes!)
- Documenting and testing backwards-compatibility with version 1.2 (it will be very limited, but I plan to include recommendations for how to migrate from v1.2 to v1.3 in at least a few limited cases).
Thanks for reading! And if this somehow magically ends up winning anything (don't know how likely that is for an in-progress patch), don't forget that yoshifanatic made major contributions to this version and should get a trophy as well.
Feel free to visit my website/blog - it's updated rarely, but it looks pretty cool!