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 (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:
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
- 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.
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.
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.