feat(template): narrat template improvements and updates + new doc pa…

…ges (#69)

* chore(templates): added templates to git

* chore(templates): new template updated to use latest vite, vue and typescript

* chore(templates and docs): template improvements and new docs

* fix(template): small fixes in new template

.gitignore

@@ -1,5 +1,9 @@
-template-games/
+# Narrat template local testing files so they're not included in releases
+dist/
+out/
+**/template/public/
 packages/create-narrat-plugin/template/
+
 built-example/
 web_modules/
 lib/

CHANGELOG.md

@@ -1,62 +1,43 @@
 # [2.14.0](https://github.com/liana-p/narrat-engine/compare/v2.13.1...v2.14.0) (2023-06-11)
 
-
 ### Features
 
-* **conditions:** new elseif conditions feature ([#68](https://github.com/liana-p/narrat-engine/issues/68)) ([1704e14](https://github.com/liana-p/narrat-engine/commit/1704e144ed0cf34c4a0f1fe580378673c530b22f))
-
-
+- **conditions:** new elseif conditions feature ([#68](https://github.com/liana-p/narrat-engine/issues/68)) ([1704e14](https://github.com/liana-p/narrat-engine/commit/1704e144ed0cf34c4a0f1fe580378673c530b22f))
 
 # [2.14.0-alpha.1](https://github.com/liana-p/narrat-engine/compare/v2.13.1...v2.14.0-alpha.1) (2023-06-10)
 
-
 ### Features
 
-* **conditions:** new elseif conditions feature ([#68](https://github.com/liana-p/narrat-engine/issues/68)) ([1704e14](https://github.com/liana-p/narrat-engine/commit/1704e144ed0cf34c4a0f1fe580378673c530b22f))
-
-
+- **conditions:** new elseif conditions feature ([#68](https://github.com/liana-p/narrat-engine/issues/68)) ([1704e14](https://github.com/liana-p/narrat-engine/commit/1704e144ed0cf34c4a0f1fe580378673c530b22f))
 
 ## [2.13.1](https://github.com/liana-p/narrat-engine/compare/v2.13.0...v2.13.1) (2023-04-16)
 
-
 ### Bug Fixes
 
-* issue with create-narrat publish ([d1a1c95](https://github.com/liana-p/narrat-engine/commit/d1a1c95c3fdf8f429c650ef71a7583b68a029620))
-
+- issue with create-narrat publish ([d1a1c95](https://github.com/liana-p/narrat-engine/commit/d1a1c95c3fdf8f429c650ef71a7583b68a029620))
 
 ### Features
 
-* **audio:** new audio resume command and fix for playing audio that was paused ([#66](https://github.com/liana-p/narrat-engine/issues/66)) ([64713de](https://github.com/liana-p/narrat-engine/commit/64713debf5a86725568fb16eef812731c6607213))
-
-
+- **audio:** new audio resume command and fix for playing audio that was paused ([#66](https://github.com/liana-p/narrat-engine/issues/66)) ([64713de](https://github.com/liana-p/narrat-engine/commit/64713debf5a86725568fb16eef812731c6607213))
 
 # [2.13.0](https://github.com/liana-p/narrat-engine/compare/v2.13.0-alpha.1...v2.13.0) (2023-04-13)
 
-
 ### Bug Fixes
 
-* **notifications:** notifications now disappear properly ([a1a8e21](https://github.com/liana-p/narrat-engine/commit/a1a8e219152c857bcb1857530e933d6d5cb2164a))
-
-
+- **notifications:** notifications now disappear properly ([a1a8e21](https://github.com/liana-p/narrat-engine/commit/a1a8e219152c857bcb1857530e933d6d5cb2164a))
 
 # [2.13.0-alpha.1](https://github.com/liana-p/narrat-engine/compare/v2.12.1...v2.13.0-alpha.1) (2023-04-13)
 
-
 ### Bug Fixes
 
-* **build:** new release process is causing issues, trying a new version ([116b02f](https://github.com/liana-p/narrat-engine/commit/116b02f8320c5cfd79d44d54597cfbf3284884bc))
-* create-narrat script issue fix ([1c6cda2](https://github.com/liana-p/narrat-engine/commit/1c6cda223de6a21e7150e1543258f7a701a0190d))
-
-
+- **build:** new release process is causing issues, trying a new version ([116b02f](https://github.com/liana-p/narrat-engine/commit/116b02f8320c5cfd79d44d54597cfbf3284884bc))
+- create-narrat script issue fix ([1c6cda2](https://github.com/liana-p/narrat-engine/commit/1c6cda223de6a21e7150e1543258f7a701a0190d))
 
 ## [2.12.1](https://github.com/liana-p/narrat-engine/compare/v2.12.0...v2.12.1) (2023-04-12)
 
-
 ### Features
 
-* **achievements:** achievement notifications ([#65](https://github.com/liana-p/narrat-engine/issues/65)) ([c6fe5b3](https://github.com/liana-p/narrat-engine/commit/c6fe5b3b69a9a24de7d4019c537b23e5380fc402))
-
-
+- **achievements:** achievement notifications ([#65](https://github.com/liana-p/narrat-engine/issues/65)) ([c6fe5b3](https://github.com/liana-p/narrat-engine/commit/c6fe5b3b69a9a24de7d4019c537b23e5380fc402))
 
 # [2.12.0](https://github.com/liana-p/narrat-engine/compare/v2.10.4...v2.12.0) (2023-04-11) - Achievements!
 
@@ -84,7 +65,7 @@ https://docs.get-narrat.com/features/achievements.html
 
 ## Breaking Changes
 
-* There is a new `saveFileName` string property that must be added to the `config.yaml` file. More info in the [saving and loading docs](https://docs.get-narrat.com/features/save-and-load.html#saving-and-reloading-1).
+- There is a new `saveFileName` string property that must be added to the `config.yaml` file. More info in the [saving and loading docs](https://docs.get-narrat.com/features/save-and-load.html#saving-and-reloading-1).
 
 # Narrat changelog
 
@@ -942,9 +923,9 @@ fix: A bug where manual saves would get overriden as autosaves in manual save mo
 
 The plugin API has been improved to allow for more features (not documented yet).
 
-There is now an [example plugin](https://github.com/liana-p/narrat/tree/main/packages/narrat-plugin-counter) in the repo that serves as an example of how to write plugin.
+There is now an [example plugin](https://github.com/liana-p/narrat-engine/tree/main/packages/narrat-plugin-counter) in the repo that serves as an example of how to write plugin.
 
-There is also a [create-narrat-plugin](https://github.com/liana-p/narrat/tree/main/packages/create-narrat-plugin) tool to easily create a plugin project, similar to the create-narrat tool.
+There is also a [create-narrat-plugin](https://github.com/liana-p/narrat-engine/tree/main/packages/create-narrat-plugin) tool to easily create a plugin project, similar to the create-narrat tool.
 
 ## 2.2.18
 
@@ -1068,7 +1049,7 @@ Syntax: `save [save_name]`: The first argument is an optional name for the save
 
 ## 2.2.12 and 2.2.13
 
-Internal architecture updates to support the new [create-narrat](https://github.com/liana-p/narrat/tree/main/packages/create-narrat) tool to generate narrat projects automatically.
+Internal architecture updates to support the new [create-narrat](https://github.com/liana-p/narrat-engine/tree/main/packages/create-narrat) tool to generate narrat projects automatically.
 
 The narrat template is now retired in favor of this new tools, and there are now multiple choices of templates in the create-narrat tool for people to use when setting up projects.
 
@@ -1235,7 +1216,7 @@ The way the system works when looking up variables is:
 
 ### New example RPG game
 
-There is now an example [dungeon crawler turn based RPG](https://github.com/liana-p/narrat/tree/main/examples/rpg) game made as a test to push the engine and scripting features. It is not meant to be a full game, but can be a useful reference for advanced usage.
+There is now an example [dungeon crawler turn based RPG](https://github.com/liana-p/narrat-engine/tree/main/examples/rpg) game made as a test to push the engine and scripting features. It is not meant to be a full game, but can be a useful reference for advanced usage.
 
 ### Anchor feature for buttons
 

README.md

@@ -4,18 +4,18 @@
 
 Narrat is a game engine for making interactive narrative RPGs packed with features.. Create your game by editing with a Simple scripting syntax. It supports Skills with skill check rolls, an Items inventory, and has a Quests System. The script system is very powerful and allows branching choices, functions, variables and conditions.
 
-Work on the engine directly in Codeflow:
+## Getting Started
+
+Go to the [Getting Started Guide](https://docs.get-narrat.com/guides/getting-started.html)
+
+Try the engine directly in your browser (experimental, only works on desktop):
 
 [![Open in Codeflow](./docs/open-in-codeflow.svg)](https://pr.new/liana-p/narrat-engine)
 
 Or try editing the default narrat game easily:
 
 [![Try editing the default game](./docs/open-in-codeflow.svg)](https:///pr.new/github.com/liana-p/narrat-engine/edit/main/packages/narrat/examples/games/default/scripts/default.nar)
 
-With Codeflow you can work on Narrat quickly without setting up an IDE
+With Codeflow you can test Narrat quickly without setting up an IDE
 
 More info on the [narrat website](https://get-narrat.com). There is an [online demo](https://get-narrat.com/demo/) available to try in the browser.
-
-## Full readme
-
-See the full readme in the [narrat package folder](https://github.com/liana-p/narrat/tree/main/packages/narrat)

docs/.vitepress/config.js

@@ -74,7 +74,10 @@ const config = {
       {
         text: 'Others',
         collapsible: true,
-        items: [{ text: 'Useful Links', link: '/others/useful-links' }],
+        items: [
+          { text: 'Useful Links', link: '/others/useful-links' },
+          { text: 'Troubleshooting', link: '/troubleshooting/troubleshooting' },
+        ],
       },
       {
         text: 'Command docs',

docs/guides/building-and-exporting.md

@@ -19,7 +19,7 @@ This will generate a built version of your game as a website in the `dist/` fold
 
 ## Building your game as an app
 
-The narrat template game is setup to use [electron](https://www.electronjs.org) to easily build a desktop application out of your game.
+The narrat template game is setup to use [electron](https://www.electronjs.org) and [electron-forge](https://www.electronforge.io) to easily build a desktop application out of your game.
 
 #### Requirements
 
@@ -41,11 +41,67 @@ npm run package
 ```
 
 ::: tip
-This will create an application for your OS in the `out/` folder
+This will create an application for your OS in the `out/` folder, which you can distribute by zipping it as a folder if desired.
 :::
 
 Please look at the [electron documentation](https://www.electronjs.org/docs/latest/) if you want to customise how your app is built, window sizes and other things (hint: Most of it takes place in the `electron-something.js` files at the root of the repo)
 
-## Building for Steam
+## Releasing on itch.io
+
+A common platform to release narrat games on is [itch.io](https://itch.io), as it's a friendly platform for small indie games.
+
+You can either release your game as a web game, or as an executable.
+
+### Web game release on itch.io
+
+Itch.io expects you to upload a zip file containing a web application, that is to say a folder containing at least a `index.html` file that has been zipped up.
+
+When you run the `npm run build` command, it will generate a `dist` folder containing a web version of your game. You can zip this `dist` folder and upload it to itch.io. as a web game, and your game should work on itch.io
+
+### Desktop Application release on itch.io
+
+To release your game as a normal desktop application on itch.io, follow the instructions for exporting your game for the OS you want to release on, and then upload that to itch.io following the normal procedure.
+
+## Generating a setup or similar package for distributing the game
+
+Electron is able to create release packages of the game for most common platforms. Included in the default setup of narrat are the configs to release for Windows, Mac and Linux.
+
+### Creating a distributable (a "setup file")
+
+To create a distributable, you need to run the following command:
+
+```bash
+npm run make
+```
+
+:::tip
+This will create a distributable for your OS in a `make` subfolder of the `out` folder.
+:::
+
+This command uses `electron-forge`'s [make](https://www.electronforge.io) command to generate a distributable like a setup for Windows, or a DMG for Mac.
+
+It uses config defined in the `config` part of the `package.json` file, which lists the makers available and their config. There you can edit some values, or add new makers.
+
+The options configured by default should help if you want to publish a simple game, but if you have more specific needs like publishing to app stores or in a specific format, see the sections below for more info on the available options.
+
+In some cases, you might need to add a new dependency to your package to use a new maker. For example you might need to run `npm install --save-dev @electron-forge/maker-pkg` to use the .pkg maker to release on the MacOS App Store.
+
+### Windows Distribution
+
+The default (and recommended by Electron) way to create a Windows distributable is to use [Squirrel.Windows](https://www.electronforge.io/config/makers/squirrel.windows), which is already configured for you in narrat games and should happen if you run `npm run make` on Windows. You can see its config in the `package.json` file.
+
+There is also the option to create a more old school .msi installer with the [WiX MSI maker](https://www.electronforge.io/config/makers/wix-msi) which you can configure in your package.json if desired.
+
+Finally, the [AppX maker](https://www.electronforge.io/config/makers/appx) can create Windows Store releases.
+
+### MacOS Distribution
+
+Running `npm run package` on a Mac should create a file that can be executed on MacOS, but if you want to distribute your app as a dmg or pkg, or on the App Store, then you should add your own config for the [DMG maker](https://www.electronforge.io/config/makers/dmg) or [pkg maker](https://www.electronforge.io/config/makers/pkg). This should allow creation of a DMG or PKG file that can be distributed either directly or on the App Store..
+
+### Linux Distribution
+
+There are all sorts of ways to distribute Linux applications depending on distributions and their package managers. The list of makers in the electron-forge list a few of the options, including [.deb](https://www.electronforge.io/config/makers/deb) and [.snap](https://www.electronforge.io/config/makers/snapcraft)
+
+## Building for Steam (experimental)
 
 [Building for Steam](/guides/steam-publishing.md)

docs/guides/theming-ui.md

@@ -22,6 +22,11 @@ This rule would give a red background color to any element with the `button` css
 
 There are two ways to use CSS to customise your UI in Narrat. One is to edit CSS variables provided to override things like common colors, and the other is to write your own CSS classes to override existing ones from the engine.
 
+::: danger
+If you use images in your css, paths should start with `/`, or the assets won't be found in the built version.
+For example: `background-image: url('/images/my-image.png');` instead of `background-image: url('images/my-image.png');`
+:::
+
 ## CSS Variables
 
 ### Introduction

docs/troubleshooting/troubleshooting.md

@@ -0,0 +1,62 @@
+---
+title: Troubleshooting
+description: This page describes troubleshooting steps for narrat issues
+---
+
+# How to debug errors
+
+Most errors on startup come from the script compiler, which usually means there is a syntax error in your script. The error box will usually tell you what the error is, but sometimes unexpected errors can happen which don't have a helpful error message. This is where more advanced troubleshooting is needed.
+
+## Opening the browser developer toold
+
+If you right click on the page and click "inspect" (on Chrome or Firefox), it will open the dev console. The usual shortcut for that is ctrl+shift+J.
+
+![dev console](./dev-console.png)
+
+### The console
+
+The `console` part of the devtools is where errors will appear. It can help find hints about issues. If the errors you find are obscure javascript error and don't help you, you can try asking for help in the narrat discord, preferably with screenshots or copy paste of all error messages you found.
+
+### The network tab
+
+Sometimes errors can be caused by a file not loading (a typo in a path for example). Looking in the network tab of the dev tools (you might have to click reload) can help see if any assets are failing to load.
+
+## Errors when building or launching the game
+
+f you get errors in the actual terminal when building the game, it means something is probably wrong with your local setup, and you should ask about those errors on the narrat discord (link on the [website](https://get-narrat.com/))
+
+## Game not launching or missing images after creating a build with electron
+
+The most common cause for this is having paths in the CSS that don't start with `/`. For example it should be `background-image: url("/img/image.png")` and not `background-image: url("img/image.png")`.
+
+## My index.html file doesn't work!
+
+You can't open the `index.html` file created by a build directly, it needs to be hosted on a server. This is because the game loads various files (images and narrat scripts for example), and [browser security policies](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) don't allow web pages to load files directly from your hard drive. You can use a local server to host the game, or upload it to a web server (for example it will work when releasing a game to itch.io).
+
+If you want an easy way to launch a local web server to test your built html game, simply go in the `dist` folder where your built game is in the terminal, and run the command `npx http-server`. This will install and run a lightweight server that lets you access your game.
+
+## Using `+`, `&&` and things like that isn't working properly
+
+Most likely issue is that you're trying to use operators like in most common programming languages (for example `if (something && somethingElse)`). But the in the narrat scripting language everything is a command, including operators. This means that the previous example should actually be `if (&& something somethingElse)`. Or for example `set data.sum (+ 1 (* 2 2))` which in this case would result in 5 (1 + 2 \* 2). Support for operators syntax might be added in the future, but for now you have to use the command syntax as the scripting language is similar to a [lisp language](https://www.tutorialspoint.com/lisp/lisp_operators.htm).
+
+## My electron build isn't updating properly
+
+Remember that the game needs to be built before running on electron by running `npm run build`. The `npm run electron` command only starts electron, but doesn't build your game.
+
+You can use `npm run desktop` as a shortcut command to first build your game and then open electron.
+
+## Errors that can be ignored
+
+::: tip
+The following errors can be safely ignored and aren't relevant
+:::
+
+### XML Parsing error in the dev console
+
+![xml-error](./xml-error.png)
+
+Those XML parsnig errors on narrat files can be ignored. For some reason, Firefox is trying to parse narrat files as an XML file. It doesn't do anything.
+
+### Security warnings on install
+
+Security warnings from npm when installing a game can be ignored. They come from the npm audit system, which is a very flawed system that flags development tools as being exploitable, even though they're never exposed to users, making those errors irrelevant to their actual use case. More background info on this [here](https://overreacted.io/npm-audit-broken-by-design/).

packages/create-narrat-plugin/package.json

@@ -31,9 +31,9 @@
   "author": "Liana Pigeot",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/liana-p/narrat/issues"
+    "url": "https://github.com/liana-p/narrat-engine/issues"
   },
-  "homepage": "https://github.com/liana-p/narrat/tree/main/packages/create-narrat#readme",
+  "homepage": "https://github.com/liana-p/narrat-engine/tree/main/packages/create-narrat#readme",
   "dependencies": {
     "kolorist": "^1.5.1",
     "minimist": "^1.2.6",

packages/create-narrat/package.json

@@ -7,12 +7,7 @@
   "bin": {
     "create-narrat": "index.js"
   },
-  "scripts": {
-    "build": "pnpm run copy-templates",
-    "preversion": "pnpm run copy-templates",
-    "prepublish": "pnpm run copy-templates",
-    "copy-templates": "node copy-templates.js"
-  },
+  "scripts": {},
   "files": [
     "index.js",
     "template*"
@@ -31,9 +26,9 @@
   "author": "Liana Pigeot",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/liana-p/narrat/issues"
+    "url": "https://github.com/liana-p/narrat-engine/issues"
   },
-  "homepage": "https://github.com/liana-p/narrat/tree/main/packages/create-narrat#readme",
+  "homepage": "https://github.com/liana-p/narrat-engine/tree/main/packages/create-narrat#readme",
   "dependencies": {
     "kolorist": "^1.5.1",
     "minimist": "^1.2.6",

packages/create-narrat/template-games/demo/data/audio.yaml

@@ -0,0 +1,23 @@
+files:
+  calm:
+    loop: true
+    src: music/music.mp3
+  battle:
+    loop: true
+    src: music/battle.mp3
+  click:
+    src: audio/click.ogg
+  game_start:
+    volume: 0.9
+    src: audio/game_start.ogg
+  failure:
+    src: audio/failure.ogg
+options:
+  volume: 0.5
+  musicFadeInTime: 0.5
+  musicFadeInDelay: 0.5
+  musicFadeOutTime: 0.5
+audioTriggers:
+  onPlayerAnswered: click
+  onPressStart: game_start
+  onSkillCheckFailure: failure