Narrat 3.0.0 with hot module reloading
This post is a bit late as the release was a few days ago, but I made this release while on holiday and never got around to posting it here.
I only bump the major version number of narrat (the first digit) for changes that impact project structure significantly, following semantic versioning guidelines. So here’s some explanation of what the big change is and why it’s important.
Hot Module Reloading
Hot module reloading (also known as hot code swapping in other languages) is simply the ability to change the code while it’s still running, without having to restart the whole program.
It’s very useful for productivity, especially when working on games, because it means you can be in the middle of a complex play session editing a specific scenario or fixing a bug, and do so without having to restart the entire playthrough.
The Hot Module Reloading (HMR) in narrat uses the Vite HMR feature. Vite is the build tool we use to build projects (narrat itself is built with it, and when you create a game project it’s vite that runs and builds it).
In the case of narrat, what this means is you can edit and save .narrat script files while keeping the game running, and next time you jump to a label in your game, it will have the latest version of the script.
See the demo video of it being used:
Why it’s a big change
Before version 3.0.0, narrat scripts were static assets that get loaded by your browser (the same way an image would be loaded) based on your config file when the game starts, and are then processed by the engine.
Now, narrat scripts are actual source files that get compiled with the game. Turning narrat files into source files is what enables the use of Vite’s HMR features to hot reload those files. This means:
- scripts aren’t listed in the config anymore
- scripts are now in the
srcfolder, alongside.tsfiles - scripts are now imported in the typescript code of the project and are treated as source files, bundled in the final javascript build of the game
- There is now a vite-plugin-narrat plugin for vite which tells Vite how to understand
.narratfiles and how to handle hot module reloading for them
All of this means that existing games need to make a few changes to use the new feature. Narrat files need to be moved around, configs need to be edited, and the code in index.ts needs to change a bit. New games created after 3.0.0 will have the new system setup by default, but existing games will need to change.
The old system of having narrat files as static assets is still supported for now, but won’t be in the future. If you’re using 3.0.0 or above, you’re strongly encouraged to take the time to update to the new system, and take advantage of the benefits of HMR.
Useful side effect for advanced users
As a side effect of all this, which scripts are loaded in the game can now be controlled directly in code. You can edit index.ts yourself to change the contents of the scripts array that gets passed to the engine.
For advanced users, this could enable conditional logic. For example you could automatically add extra narrat debug scripts or different versions of them depending on if you’re making a dev build or a public release build.
Future changes it enables
This is the first step of making narrat more modular and customisable. This won’t be very relevant to most users, but as more and more people ask for advanced features or more control over the engine, having the ability to control more things via typescript (or javascript) code for advanced users can be useful.
For example, eventually I’d like to make it possible to let games load and provide the config on their own (so that games could use code to dynamically tweak config). Another example is being able to create the Narrat vue app and access it yourself to inject it wherever you want or enable other advanced changes to the engine for people who can make use of vuejs to override some UI templates or create dynamic game demos integrated into web pages or other engines.
Of course the overall goal is to keep narrat simple, so all those potential features would still be optional, or made in a way that people don’t need to know about them to use narrat. For example, for new projects created after 3.0.0, HMR works seamlessly and requires no setup.