` | The grid that holds one `

` per asset. | | `image-viewer` | `

` | The full-screen viewer shown when an unlocked image is clicked. | Only unlocked figures carry a `data-image` attribute (the asset key), which is what makes them clickable. ## The Image Viewer When the player clicks an unlocked `

`, the screen activates the viewer by adding `modal--active` to the `image-viewer` element and setting the figure's `background-image` to the full-size asset. Clicking anywhere on the open viewer closes it again and clears the background. > [!TIP] > The whole viewer closes on click, so there is no separate close button. If you want one, you can add it in your own theme and bind it to the same behaviour. ## State | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `open` | `boolean` | `false` | Whether the screen is open. Inherited from the base screen component; toggles the `active` class. | | `unlocked` | `string[]` | `[]` | The asset keys the player has unlocked. Loaded from `Storage` when the screen mounts. | When `unlocked` changes, the component saves the new list back to `Storage` under `gallery` and re-renders the grid. ## Styling ```css /* The screen container */ gallery-screen { /* Inherits base screen styles; shown when active */ } /* The grid of images */ gallery-screen [data-ui="gallery"] { display: flex; flex-wrap: wrap; } /* Each image card */ gallery-screen figure { background-size: cover; background-position: center; } /* The lock icon on locked entries */ gallery-screen figure .fa-lock { /* Lock styling */ } /* The full-screen viewer */ gallery-screen [data-ui="image-viewer"] { /* Modal viewer styling */ } /* The viewer's image area */ gallery-screen [data-ui="image-viewer"] figure { background-size: contain; background-repeat: no-repeat; background-position: center; } /* The back button */ gallery-screen [data-action="back"] { /* Back button styling */ } ``` ## Related - [Gallery Action](/v2/script-actions/image-gallery) - Locks and unlocks gallery images from your script - [Main Menu](/v2/components/main-menu) - Gains a Gallery button when gallery assets are defined - [Show Image](/v2/script-actions/show-image) - Display images during gameplay --- # Message Modal > A modal with a title, subtitle and body shown by the Show Message action, which blocks the game until the player closes it. Source: https://monogatari.io/v2/components/message-modal Section: Documentation ## Description ```markup ``` The message-modal component displays a modal window with an optional title, an optional subtitle and a body of text, plus a single button to close it. It is shown by the [Show Message action](/v2/script-actions/message) and is meant for short, in-script messages such as notes, hints or warnings. While a message modal is open, the game cannot advance until the player closes it. **Source Code**: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/message-modal](https://github.com/Monogatari/Monogatari/tree/develop/src/components/message-modal) ## Usage Message modals are not created directly. They are shown from the script with the `show message` statement, where `` is the key of a message you registered beforehand: ```javascript 'show message Help' ``` You can also append custom CSS classes after the id: ```javascript 'show message Help fullscreen' ``` Messages themselves are registered with `monogatari.messages ()`: ```javascript monogatari.messages ({ 'Help': { title: 'Help', subtitle: 'Some useful information', body: 'This is the body of the message shown to the player.' } }); ``` The action reads the message, fills the modal's props with the message fields (running each through variable replacement) and appends a `` to the game screen. See the [Show Message action](/v2/script-actions/message) for the full message format. ## Structure The component renders a content container with a message section and a single close button: ```html ``` The `title`, `subtitle` and `body` elements are only rendered when their corresponding prop is a non-empty string, so a message with only a body will render just the `

` | | `subtitle` | `string \| null` | `null` | The message subtitle, rendered as a `
` | | `body` | `string` | `''` | The main message text, rendered as a `
` | | `actionString` | `string` | `'Close'` | A translation key used for the close button's label, resolved with `monogatari.string ()` | > [!NOTE] > The title, subtitle and body props are rendered as-is (they are filled with the message text after variable replacement). Only `actionString` is treated as a translation key. The button text is therefore `monogatari.string (actionString)`, defaulting to the translated `Close` string. ## Blocking Behavior The message modal blocks the game from proceeding while it is open. This is handled in two places: - The [Show Message action](/v2/script-actions/message) sets a `blocking` flag while the modal is visible and rejects `shouldProceed` until the player clicks the close button. - The component itself overrides `shouldProceed` to reject (`'Message Modal awaiting for user to close the modal window.'`), so any attempt to advance, auto-play or skip is prevented until the modal is removed. The close button carries both `data-action="close"` and `data-close="message-modal"`. When clicked, the action's listener clears the blocking flag, removes the modal and lets the game proceed. ## Methods The message-modal overrides several lifecycle methods. All of them simply remove the modal from the DOM when the relevant event occurs. | Method | Behavior | | :--- | :--- | | `shouldProceed()` | Always rejects, blocking advancement while the modal is open | | `willProceed()` | Removes the modal | | `willRollback()` | Removes the modal so the game can revert to the previous statement | | `onReset()` | Removes the modal when the game is reset | | `willMount()` | Adds the `modal` and `modal--active` classes | ## Styling ```css /* Main container (uses the shared .modal styles) / message-modal { / Modal base styles inherited from the .modal class / } message-modal div { width: auto; padding: 1rem; } message-modal a { color: #00bcd4; } / Message content is left-aligned and selectable / message-modal [data-ui="message-content"] { text-align: left; max-width: 100%; } message-modal [data-ui="message-content"] { user-select: text; } ``` ## Related - [Show Message Action](/v2/script-actions/message) - Registers messages and shows this modal - [Alert Modal](/v2/components/alert-modal) - A related confirmation modal opened from JavaScript - [Text Box](/v2/components/text-box) - Displays regular dialog --- # Text Input > A flexible modal input component used by the Input action to collect text, numbers, and choices from the player. Source: https://monogatari.io/v2/components/text-input Section: Documentation ## Description ```markup ``` The text-input component is the modal dialog that asks the player for information: their name, a password, a selection from a list, and so on. It is created automatically by the [Input action](/v2/script-actions/input), which passes it the text to show, the input type, validation and save callbacks, and other options. You normally never write `` yourself; you configure it through the Input action. ![A text input prompt|A text input collecting the player's name, shown over the game with the quick menu below.](https://cdn.restlessdreams.cloud/307b2987-4511-4a83-8b15-8406caec8303.webp) Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/text-input](https://github.com/Monogatari/Monogatari/tree/develop/src/components/text-input) ## Supported Input Types The `type` prop selects which form control is rendered. The following types are supported: | Category | Types | | :--- | :--- | | Text fields | `text`, `password`, `email`, `url`, `number`, `color`, `file`, `date`, `datetime-local`, `month`, `time`, `week`, `tel`, `range` | | Multi-line | `textarea` | | Single choice | `select`, `radio` | | Multiple choice | `checkbox` | A single-line field is rendered as an `` of the matching native type. `textarea` renders a ``. `select` renders a dropdown built from `options`. `radio` and `checkbox` render one labelled control per entry in `options`. > [!NOTE] > For `checkbox`, the submitted value is an array of the checked values. Every other type submits a single string (an empty string when nothing was entered or selected). ## Structure The component renders a form inside a modal. The shape of the input region depends on the `type`: ```html <text-input class="modal modal--active" data-component="text-input"> <form class="modal__content"> <p data-content="message">What is your name?</p>  <input data-content="field" name="field" type="text" tabindex="0"> <small data-content="warning" class="block"></small> <div> <button type="submit" tabindex="0">OK</button> </div> </form> </text-input> ``` For `select`, the field becomes a `<select data-content="field">` containing one `<option>` per entry. For `radio` and `checkbox`, each option is rendered as: ```html <div class="input-pair"> <input data-content="field" id="field_0" name="field" type="radio" value="pink" tabindex="0"> <label for="field_0">Pink</label> </div> ``` ### Data Content Keys | Key | Element | Description | | :--- | :--- | :--- | | `message` | `<p>` | The prompt text shown to the player (from the `text` prop). | | `field` | input / textarea / select | The control(s) the player interacts with. | | `warning` | `<small>` | Where the validation warning is shown when input is invalid. | ## State | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `active` | `boolean` | `true` | Whether the modal is active. When set to `true`, the `modal--active` class is toggled. | ## Props The Input action sets these props for you. The names below are the component's prop names, with the matching Input action property noted. | Prop | Type | Default | Input Action Property | Description | | :--- | :--- | :--- | :--- | :--- | | `text` | `string` | `''` | `Text` | The prompt shown to the player. | | `type` | `string` | `'text'` | `Type` | One of the [supported input types](#supported-input-types). | | `default` | `string \| number \| null` | `null` | `Default` | Pre-filled value. For text fields it fills the field; for `select`/`radio`/`checkbox` it matches an option's `value`. | | `options` | `array` | `[]` | `Options` | Choices for `select`, `radio`, and `checkbox`. Each entry has `label` and `value`. | | `warning` | `string` | `''` | `Warning` | Message shown when validation fails. | | `actionString` | `string` | `'OK'` | `actionString` | Translation key for the submit button label. | | `onSubmit` | `function` | no-op | `Save` | Receives the value once it passes validation. | | `validate` | `function` | returns `true` | `Validation` | Receives the value and returns (or resolves to) a boolean. | | `callback` | `function` | no-op | (internal) | Run after submission completes; used by the action to resume the game. | | `classes` | `string` | `''` | `Class` | Space-separated CSS class names added to the modal. | | `attributes` | `object` | `{}` | `Attributes` | HTML attributes applied to the field (e.g. `placeholder`, `maxlength`). | > [!NOTE] > An `InputOption` is an object with a `value` (`string` or `number`) and a `label` (`string`). Labels and string values are run through variable interpolation when rendered. ## Validation and Submit Flow When the player submits the form, the component: 1. Reads the value from the field. For `radio` it takes the checked option's value (or an empty string if none is checked); for `checkbox` it collects every checked value into an array; otherwise it reads the field's value as a string. 2. Runs the `validate` function with that value. Validation may be synchronous or return a `Promise`. 3. If validation passes, it runs `onSubmit` with the value, then removes itself from the DOM and runs `callback`. 4. If validation fails, the input stays open and the `warning` text (with variables interpolated) is shown in the `warning` element. Because both `validate` and `onSubmit` are awaited, you can perform asynchronous work (such as a server request) in either of them. For text-based fields (`text`, `textarea`, `password`, `email`, `url`, `number`, `color`), the `default` value is applied after the component mounts so the cursor lands at the end of the pre-filled text. The field is focused automatically when the modal opens. ## Blocking Advancement While a text-input is open, the game cannot advance: ```typescript shouldProceed (): Promise<void> { return Promise.reject('Input is awaiting user input.'); } ``` The component's `shouldProceed` always rejects, so attempts to proceed (clicking, auto-play, skip) are refused until the player submits a valid value. Submission removes the component and runs the `callback`, which is what lets the [Input action](/v2/script-actions/input) resume the script. > [!WARNING] > When the player rolls back to an input, the component removes itself (`willRollback`). The Input action only allows rolling back through an input when its `Revert` function is defined, so always provide one if you want players to be able to go back. ## Styling ```css /* The modal container / text-input { / Inherits base .modal styles / } / Active state / text-input.modal--active { display: flex; } / The form holding the prompt, field and button / text-input .modalcontent { / Layout for the input dialog / } / The prompt text / text-input [data-content="message"] { / Prompt styling / } / The input field itself / text-input [data-content="field"] { width: 100%; } / The validation warning / text-input [data-content="warning"] { color: #d32f2f; } / A radio/checkbox option row / text-input .input-pair { display: flex; align-items: center; } ``` To style only specific inputs, pass a `Class` through the Input action; those classes are added to the `text-input` element and can be targeted in your CSS. ## Related - [Input Action](/v2/script-actions/input) - Creates and configures the text-input - [Choices](/v2/script-actions/choices) - An alternative way to ask the player to pick an option - [Message](/v2/script-actions/message) - Show a modal message without collecting input --- # Load Screen > The in-game load screen listing manual saves and, when enabled, auto-saves for the player to resume. Source: https://monogatari.io/v2/components/load-screen Section: Documentation ## Description ```markup <load-screen></load-screen> ``` The load-screen component lets the player resume a previously saved game. It renders a list of the player's manual saves and, when auto-saving is enabled, a second list of auto-saves. Clicking a slot loads that game and continues play from where it was saved. ![The default load screen|The load screen, with its "Saved Games" and (when auto-save is on) "Auto Saved Games" slot lists.](https://cdn.restlessdreams.cloud/0938137d-18fa-4584-87b3-40240a3ea2c5.webp) Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/load-screen](https://github.com/Monogatari/Monogatari/tree/develop/src/components/load-screen) ## Usage The load-screen is a screen component, so it is shown like any other screen: ```javascript // Open the load screen monogatari.showScreen('load'); ``` While a game is playing, the keyboard shortcut `Shift + L` opens the load screen. ## Structure The load-screen renders the following structure: ```html <load-screen data-component="load-screen" data-screen="load"> <button class="top left" data-action="back"><span class="fas fa-arrow-left"></span></button> <h2 data-string="Load">Load</h2> <div data-ui="saveSlots"> <h3 data-string="LoadSlots">Saved Games</h3> <div data-ui="slots"> <slot-container label="Save" type="load"></slot-container> </div> </div>  <div data-ui="autoSaveSlots"> <h3 data-string="LoadAutoSaveSlots">Auto Saved Games</h3> <div data-ui="slots" data-content="slots"> <slot-container label="AutoSave" type="load"></slot-container> </div> </div> </load-screen> ``` The two `<slot-container>` elements are rendered in `load` mode. Their `label` attributes come from the [`SaveLabel`](/v2/configuration-options/game-configuration/saving) (default `Save`) and [`AutoSaveLabel`](/v2/configuration-options/game-configuration/saving) (default `AutoSave`) settings. The `data-screen="load"` attribute and the `active` class are managed automatically by the base screen component. > [!NOTE] > The auto-saved section is only rendered when the [`AutoSave`](/v2/configuration-options/game-configuration/saving) setting is a number greater than `0` (its value is the interval in minutes). When auto-save is disabled, the entire `autoSaveSlots` block is omitted. ## State The load-screen inherits its state from the base screen component. | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `open` | `boolean` | `false` | Whether the screen is currently open. When `true`, the `active` class is added to the element. | ## Slot Lists The load-screen does not list slots itself; it delegates to the [`slot-container`](/v2/components/save-slot) component, one per list: | List | Heading string | slot-container label | | :--- | :--- | :--- | | Saved Games | `LoadSlots` | `SaveLabel` setting (default `Save`) | | Auto Saved Games | `LoadAutoSaveSlots` | `AutoSaveLabel` setting (default `AutoSave`) | Each slot in those containers is a [Save Slot](/v2/components/save-slot). When a container has no saves to show, it displays the `NoSavedGames` message instead of slots. ## Loading Flow Because both containers are created with `type="load"`, clicking a slot loads it. The slot-container loads the chosen save and then resumes play from the saved position. Clicking a slot's delete button removes that save instead of loading it. > [!TIP] > The save/load flow itself lives in the [slot-container](/v2/components/save-slot) component. The load-screen's job is to render the headings and the two `load`-mode containers; the click-to-load and delete handling come from the container. ## Localization The screen uses `data-string` attributes for translatable text: | String Key | Default | Description | | :--- | :--- | :--- | | `Load` | "Load" | Screen title | | `LoadSlots` | "Saved Games" | Heading for the manual saves list | | `LoadAutoSaveSlots` | "Auto Saved Games" | Heading for the auto-saves list | ## Styling The load-screen can be styled with CSS against its real selectors: ```css / The screen itself / load-screen { / Your styles / } / Only when the screen is open / load-screen.active { / Visible state / } / Manual saves section / load-screen [data-ui="saveSlots"] { / Layout for the manual saves list / } / Auto-saves section / load-screen [data-ui="autoSaveSlots"] { / Layout for the auto-saves list / } ``` ## Customizing ### Restyle the lists The two lists live in `data-ui="saveSlots"` and `data-ui="autoSaveSlots"`, each wrapping a `data-ui="slots"` row that holds a `<slot-container>`. Target those to lay out or restyle the screen: ```css / Manual saves section / load-screen [data-ui="saveSlots"] { / Your styles / } / Auto-saves section / load-screen [data-ui="autoSaveSlots"] { / Your styles / } / The row that holds the slots / load-screen [data-ui="slots"] { display: grid; grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); gap: 1rem; } ``` To restyle the slots themselves, see [Save Slot](/v2/components/save-slot) — the load-screen only renders the headings and the two `load`-mode containers. ### Change the structure To change the markup (for example to drop the headings or reorder the lists), override it with the [`template()`](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure) function. Keep the `<slot-container … type="load">` elements so the slots are still listed and clicking one still loads it. ## Related - [Save Slot](/v2/components/save-slot) - The individual slot markup and the slot list container - [Save Screen](/v2/components/save-screen) - Where players create new saves - [Saving](/v2/configuration-options/game-configuration/saving) - Save labels, auto-save interval, and screenshots configuration - [Settings Screen](/v2/components/settings-screen) - The in-game options panel --- # Alert Modal > A confirmation modal with a message and custom action buttons, used for quit, slot deletion and slot overwrite confirmations. Source: https://monogatari.io/v2/components/alert-modal Section: Documentation ## Description ```markup <alert-modal></alert-modal> ``` The alert-modal component displays a confirmation message along with one or more buttons that the player must choose from. It is the engine's general-purpose dialog for "Are you sure?" interactions, such as confirming a quit, deleting a save slot or overwriting an existing save slot. An alert can optionally show extra context (for example, the name of the slot being deleted) and can even include a text input. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/alert-modal](https://github.com/Monogatari/Monogatari/tree/develop/src/components/alert-modal) ## Usage Alert modals are not placed in the script. They are created on demand from JavaScript using the `monogatari.alert ()` helper, which builds an `<alert-modal>`, sets its props and prepends it to the engine element: ```javascript monogatari.alert ('quit-warning', { message: 'Confirm', actions: [ { label: 'Quit', listener: 'quit' }, { label: 'Cancel', listener: 'dismiss-alert' } ] }); ``` The first argument is an `id` that is stored on the element as a `data-alert-id` attribute. It lets you dismiss a specific alert later: ```javascript // Remove the alert with the given id monogatari.dismissAlert ('quit-warning'); // Remove every alert currently on screen monogatari.dismissAlert (); ``` ## Structure The component renders a single content wrapper with the message, an optional context element and a row of action buttons: ```html <alert-modal class="modal modal--active" data-alert-id="quit-warning"> <div class="modalcontent" data-content="wrapper"> <p data-string="Confirm" data-content="message">Do you want to quit?</p> <div data-content="actions"> <button data-action="quit" data-string="Quit">Quit</button> <button data-action="dismiss-alert" data-string="Cancel">Cancel</button> </div> </div> </alert-modal> ``` When the alert is given a `context` value, an extra element is rendered between the message and the actions. By default it is a `<small>` element, but if `editable` is `true` it becomes a text `<input>` instead: ```html  <small data-content="context">My Save File</small>  <input type="text" data-content="context" value="My Save File" /> ``` ## Content Areas | Name | Selector | Description | | :--- | :--- | :--- | | `wrapper` | `[data-content="wrapper"]` | The modal content container | | `message` | `[data-content="message"]` | The confirmation message text | | `context` | `[data-content="context"]` | Optional extra context (only rendered when `context` is set) | | `actions` | `[data-content="actions"]` | The container holding the action buttons | ## Props The alert-modal is configured entirely through its props, which are typically supplied by `monogatari.alert ()`. | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `active` | `boolean` | `true` | Whether the modal is shown. Toggling it to `true` toggles the `modal--active` class | | `message` | `string` | `''` | A translation key. The text is resolved with `monogatari.string (message)` and rendered with a matching `data-string` attribute | | `context` | `string \| null` | `null` | Optional extra text shown below the message. When omitted, no context element is rendered | | `editable` | `boolean` | `false` | When `true` (and `context` is set), the context is rendered as a text `<input>` instead of a `<small>` element | | `actions` | `Action[]` | `[]` | The list of buttons to render (see below) | > [!NOTE] > The `message` prop is a translation key, not literal text. It is passed through `monogatari.string ()`, so the key must exist in your translations. The built-in keys used by the engine are `Confirm` (quit), `SlotDeletion` and `SlotOverwrite`. ## Actions Each entry in the `actions` array describes one button. Buttons render with a `data-action` attribute set to the action's `listener` and a `data-string` set to its `label`: | Field | Type | Description | | :--- | :--- | :--- | | `label` | `string` | A translation key used both as the button text (`monogatari.string (label)`) and its `data-string` attribute | | `listener` | `string` | The name of the registered listener that fires when the button is clicked. It becomes the button's `data-action` value | The engine registers a built-in `dismiss-alert` listener that simply removes the alert, which is why most alerts include a "Cancel" button pointing at it: ```javascript { label: 'Cancel', listener: 'dismiss-alert' } ``` Other listeners are registered by whichever feature opens the alert. For example, the [End action](/v2/script-actions/end) registers a `quit` listener, the save slot registers `delete-slot` and the slot container registers `overwrite-slot`. ## Typical Uses ### Quit Confirmation When the player presses `Shift + Q` (or tries to close a desktop build), a quit confirmation is shown using the `Confirm` message and `quit` / `dismiss-alert` actions: ```javascript monogatari.alert ('quit-warning', { message: 'Confirm', actions: [ { label: 'Quit', listener: 'quit' }, { label: 'Cancel', listener: 'dismiss-alert' } ] }); ``` ### Slot Deletion When the player deletes a save slot, the alert shows the slot's name (or date) as context: ```javascript monogatari.alert ('slot-deletion', { message: 'SlotDeletion', context: saveData.name, actions: [ { label: 'Delete', listener: 'delete-slot' }, { label: 'Cancel', listener: 'dismiss-alert' } ] }); ``` ### Slot Overwrite When the player overwrites an existing slot, the alert is `editable` so the player can rename the save: ```javascript monogatari.alert ('slot-overwrite', { message: 'SlotOverwrite', context: saveData.name, editable: true, actions: [ { label: 'Overwrite', listener: 'overwrite-slot' }, { label: 'Cancel', listener: 'dismiss-alert' } ] }); ``` ## Styling ```css / Main container (uses the shared .modal styles) / alert-modal { / Modal base styles inherited from the .modal class / } / Active state / alert-modal.modal--active { / Shown when the active prop is true / } / Content wrapper / alert-modal [data-content="wrapper"] { overflow: auto; overflow-x: hidden; flex-direction: column; } / Message text / alert-modal p { font-size: 1.5rem; } / Editable context input / alert-modal input[type="text"] { margin-bottom: 2rem; text-align: center; } ``` ## Related - [End Action](/v2/script-actions/end) - Registers the `quit` listener used by the quit confirmation - [Save Slot](/v2/components/save-slot) - Opens the slot deletion alert - [Settings Screen](/v2/components/settings-screen) - Triggers the quit confirmation on desktop builds - [Message Modal](/v2/components/message-modal) - A related modal driven from the script --- # Save Screen > The in-game save screen where players name a save and store their current progress into a slot. Source: https://monogatari.io/v2/components/save-screen Section: Documentation ## Description ```markup <save-screen></save-screen> ``` The save-screen component lets the player store their current progress. It renders a text input for naming the save, a Save button, and the list of existing save slots. Saving creates a new slot (or overwrites an existing one) labelled with the name the player typed. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/save-screen](https://github.com/Monogatari/Monogatari/tree/develop/src/components/save-screen) ## Usage The save-screen is a screen component, so it is shown like any other screen: ```javascript // Open the save screen monogatari.showScreen('save'); ``` While a game is playing, the keyboard shortcut `Shift + S` opens the save screen. ## Structure The save-screen renders the following structure: ```html <save-screen data-component="save-screen" data-screen="save"> <button class="top left" data-action="back"><span class="fas fa-arrow-left"></span></button> <div class="horizontal horizontal--center"> <input type="text" placeholder="Save Slot Name" data-input="slotName" data-content="slot-name" required> <button data-string="Save" data-action="save">Save</button> </div> <div data-ui="slots" data-content="slots"> <slot-container label="Save" type="save"></slot-container> </div> </save-screen> ``` The `label` on the inner `<slot-container>` comes from the [`SaveLabel`](/v2/configuration-options/game-configuration/saving) setting (default `Save`). The `data-screen="save"` attribute and the `active` class are managed automatically by the base screen component. > [!NOTE] > The slot list is rendered by the separate [`slot-container`](/v2/components/save-slot) component, which in turn renders each [Save Slot](/v2/components/save-slot). This page documents the save screen's own input and save flow; see those pages for the slot markup and behaviour. ## State The save-screen inherits its state from the base screen component. | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `open` | `boolean` | `false` | Whether the screen is currently open. When it becomes `true`, the slot-name input is pre-filled with the current date and time, and the `active` class is added. | ## Content Areas | Name | Selector | Description | | :--- | :--- | :--- | | `slot-name` | `[data-content="slot-name"]` | The text input where the player names the save. | | `slots` | `[data-content="slots"]` | Container holding the `<slot-container>` that lists existing saves. | ## Save Flow The screen registers a listener for the `save` action that the Save button triggers: 1. When the screen is opened, the slot-name input is filled with the current date and time (formatted with [Luxon](https://moment.github.io/luxon/)), giving the player a sensible default name. 2. The player may type a custom name, then press the Save button (`data-action="save"`). 3. The listener reads the trimmed value of the slot-name input. If it is not empty, it saves the current game state using that name under the [`SaveLabel`](/v2/configuration-options/game-configuration/saving) prefix, creating a new slot. ```javascript // What the Save button effectively does (with the typed name) monogatari.saveTo('SaveLabel', null, slotName); ``` > [!TIP] > Clicking an existing slot in the list saves over* that slot instead of creating a new one. That overwrite confirmation flow is handled by the [slot-container](/v2/components/save-slot) component, not by the save screen itself. > [!WARNING] > If the slot-name input is empty, the Save button does nothing. The input is marked `required`, and the listener ignores empty or whitespace-only names. ## Localization The screen uses `data-string` attributes for translatable text: | String Key | Default | Description | | :--- | :--- | :--- | | `Save` | "Save" | The Save button label | The placeholder text (`Save Slot Name`) is a static attribute on the input. ## Styling The save-screen can be styled with CSS against its real selectors: ```css /* The screen itself / save-screen { / Your styles / } / Only when the screen is open / save-screen.active { / Visible state / } / The slot-name input / save-screen input { background-color: #fff; border: 1px solid #666; } / Slot list area / save-screen [data-content="slots"] { / Layout for the list of save slots / } ``` ## Related - [Save Slot](/v2/components/save-slot) - The individual slot markup and the slot list container - [Load Screen](/v2/components/load-screen) - Where players resume a saved game - [Saving](/v2/configuration-options/game-configuration/saving) - Save labels, auto-save, and screenshots configuration - [Settings Screen](/v2/components/settings-screen) - The in-game options panel --- # Main Menu > The game's main menu screen, rendering the buttons players use to start, load, and configure the game. Source: https://monogatari.io/v2/components/main-menu Section: Documentation ## Description ```markup <main-menu></main-menu> ``` The main-menu component renders the menu shown when the game first loads. Each entry it displays (Start, Load, Settings, etc.) comes from its configuration, so you can add, remove, or reorder buttons without ever touching the component's markup. ![The default main menu|The default main menu — Start, Load, Settings and Help.](https://cdn.restlessdreams.cloud/ec936539-f9e9-4628-b2ed-7ca8f5be4ee4.webp) Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/main-menu](https://github.com/Monogatari/Monogatari/tree/develop/src/components/main-menu) ## Default Buttons Out of the box the main menu ships with the following buttons, in this order: | String | Action | Description | | :--- | :--- | :--- | | `Start` | `start` | Begins a new game. | | `Load` | `open-screen` (opens `load`) | Opens the load screen to resume a saved game. | | `Settings` | `open-screen` (opens `settings`) | Opens the settings screen. | | `Help` | `open-screen` (opens `help`) | Opens the help screen. | > [!NOTE] > The default main menu buttons are defined without an `icon`, so they render as text only. If you add your own buttons with an `icon` value, that icon is rendered as a `<span>` before the label. ## Buttons Added By Other Components Some buttons are not part of the default configuration. They are added automatically by other components, but only when the relevant content exists: | String | Added By | Condition | | :--- | :--- | :--- | | `Gallery` | [Gallery Screen](/v2/components/gallery-screen) | At least one image is registered with `monogatari.assets('gallery', { ... })`. | | `Credits` | [Credits Screen](/v2/components/credits) | At least one entry is registered with `monogatari.configuration('credits', { ... })`. | Both buttons are inserted with `addButton`, so they appear at the end of the menu. ## Structure The main menu renders one element per configured button. A simple button with an icon produces the following markup: ```html <main-menu data-component="main-menu"> <button icon="" string="Start" tabindex="0" data-action="start"> <span class=""></span> <span data-string="Start">Start</span> </button> <button icon="" string="Load" tabindex="0" data-action="open-screen" data-open="load"> <span class=""></span> <span data-string="Load">Load</span> </button>  </main-menu> ``` For each button, the component: - Creates a `button` element (or the tag named in the button's `element` property). - Copies every key of the button's `data` object onto the element as a `data-` attribute. - Sets the `icon`, `string`, and `tabindex="0"` attributes. - Renders the icon class inside a `<span>` and the translated label inside a `<span data-string="…">`. ## Button Definition Each button is described by a `MenuButton` object: | Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | `string` | `string` | Yes | Translation key used for the label and as the button's unique identifier. | | `icon` | `string` | Yes | CSS class(es) for the icon, e.g. a [Font Awesome](https://fontawesome.com/) class. Use an empty string for no icon. | | `data` | `object` | No | Key/value pairs rendered as `data-` attributes. Use `action` here to bind the button to an engine action. | | `element` | `string` | No | Tag name to render instead of `button`. Defaults to `button`. | ## Adding, Removing, and Reordering Buttons The main menu inherits its button API from `MenuComponent`. Call these static methods on the component to change which buttons are shown. Every call re-renders all instances of the menu automatically. ### Add Button ```javascript static addButton (button: MenuButton): void ``` Adds a button to the end of the menu. ```javascript monogatari.component ('main-menu').addButton ({ string: 'About', icon: 'fas fa-info-circle', data: { action: 'open-screen', open: 'about' } }); ``` ### Add Button After ```javascript static addButtonAfter (after: string, button: MenuButton): void ``` Adds a button immediately after the button whose `string` matches the `after` argument. If no such button exists, nothing is added. ```javascript monogatari.component ('main-menu').addButtonAfter ('Start', { string: 'Continue', icon: 'fas fa-play', data: { action: 'open-screen', open: 'load' } }); ``` ### Add Button Before ```javascript static addButtonBefore (before: string, button: MenuButton): void ``` Adds a button immediately before the button whose `string` matches the `before` argument. If no such button exists, nothing is added. ```javascript monogatari.component ('main-menu').addButtonBefore ('Settings', { string: 'Achievements', icon: 'fas fa-trophy', data: { action: 'open-screen', open: 'achievements' } }); ``` ### Remove Button ```javascript static removeButton (string: string): void ``` Removes every button whose `string` matches the given value. ```javascript monogatari.component ('main-menu').removeButton ('Help'); ``` ### Get Buttons ```javascript static buttons (): MenuButton[] ``` Returns the full array of button definitions currently configured. ### Get a Single Button ```javascript static button (string: string): MenuButton | undefined ``` Returns the button definition whose `string` matches the given value, or `undefined` if there is none. > [!TIP] > Because buttons are stored in the component's configuration, you can also set the entire list at once with `monogatari.component ('main-menu').configuration ('buttons', [...])`. The per-button helpers above are the safer choice when you only need to change one entry. ## Styling The main menu is a [screen](/v2/components/main-screen) target. Style its buttons through the `main-menu` tag: ```css / The main menu container / main-menu { display: flex; flex-direction: column; } / Every button in the menu / main-menu button { cursor: pointer; } / Target a specific button by its action / main-menu [data-action="start"] { font-weight: bold; } / The icon span rendered before the label / main-menu button span:first-child { margin-right: 0.5em; } / The label span / main-menu button [data-string] { / Label styling / } ``` ## Related - [Main Screen](/v2/components/main-screen) - The screen that hosts the main menu - [Quick Menu](/v2/components/quick-menu) - The in-game menu that shares the same button API - [Gallery Screen](/v2/components/gallery-screen) - Adds the Gallery button when images are defined - [Credits Screen](/v2/components/credits) - Adds the Credits button when credits are defined --- # Settings Screen > The in-game settings screen with volume, text speed, auto-play, language and (on desktop) resolution controls. Source: https://monogatari.io/v2/components/settings-screen Section: Documentation ## Description ```markup <settings-screen></settings-screen> ``` The settings-screen component renders the in-game options panel where players adjust their [Player Preferences](/v2/configuration-options/player-preferences): the per-source audio volumes, the typewriter text speed, the auto-play delay, the game/UI language (for multi-language games) and, on desktop builds, the window resolution. Every control reads its initial value from the saved preference and writes the player's choice straight back to it, so the changes persist between sessions. ![The default settings screen|The settings screen — per-source volume sliders, text speed, and auto-play speed (language and resolution appear when enabled).](https://cdn.restlessdreams.cloud/758ecb31-8616-4ca3-af19-e89ec8370dd0.webp) Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/settings-screen](https://github.com/Monogatari/Monogatari/tree/develop/src/components/settings-screen) ## Usage The settings-screen is a screen component, so it is shown and hidden like any other screen: ```javascript // Open the settings screen monogatari.showScreen('settings'); ``` While a game is playing, pressing `Esc` toggles between the game and the settings screen. ## Structure The settings-screen renders the following structure: ```html <settings-screen data-component="settings-screen" data-screen="settings"> <button class="top left" data-action="back"><span class="fas fa-arrow-left"></span></button> <h2 data-string="Settings">Settings</h2> <div class="settings"> <div class="settings-group"> <div data-settings="audio" class="vertical vertical--center text--center" data-content="audio-settings"> <h3 data-string="Audio">Audio</h3> <span data-string="Music">Music Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="music"> <span data-string="Sound">Sound Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="sound"> <span data-string="Voice">Voice Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="voice"> <span data-string="Video">Video Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="video"> </div> </div> <div class="settings-group"> <div data-settings="text-speed"> <h3 data-string="TextSpeed">Text Speed</h3> <input type="range" min="1" max="50" step="1" data-action="set-text-speed"> </div> <div data-settings="auto-play-speed"> <h3 data-string="AutoPlaySpeed">Auto Play Speed</h3> <input type="range" min="0" max="60" step="1" data-action="set-auto-play-speed" data-content="auto-play-speed-controller"> </div> <div data-settings="language" data-content="language-settings"> <h3 data-string="Language">Language</h3> <div class="horizontal horizontal--center" data-content="wrapper"></div> </div> <div data-settings="resolution" data-platform="desktop"> <h3 data-string="Resolution">Resolution</h3> <div class="horizontal"> <select data-action="set-resolution"></select> <span class="fas fa-sort" data-select="set-resolution"></span> </div> </div> </div> </div> </settings-screen> ``` The `data-screen="settings"` attribute is added automatically by the base screen component, and `active` is toggled on the element when the screen is opened. > [!NOTE] > The language and resolution sections are not always present at runtime. The language dropdown is only built when the [`MultiLanguage`](/v2/configuration-options/game-configuration/internationalization) setting is `true`; otherwise the whole `language-settings` block is removed. The resolution block is only kept on desktop (Electron / Electrobun) builds; on the web it is removed. ## State The settings-screen inherits its state from the base screen component. | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `open` | `boolean` | `false` | Whether the screen is currently open. When `true`, the `active` class is added to the element. | ## Controls and Preferences Each control maps to a value in [Player Preferences](/v2/configuration-options/player-preferences). The screen initializes every control from the matching preference when the engine finishes initializing, and writes the new value back when the player interacts with it. | Control | Element | Action | Preference written | | :--- | :--- | :--- | :--- | | Music volume | `input[type="range"]` (`data-target="music"`) | `set-volume` | `Volume.Music` | | Sound volume | `input[type="range"]` (`data-target="sound"`) | `set-volume` | `Volume.Sound` | | Voice volume | `input[type="range"]` (`data-target="voice"`) | `set-volume` | `Volume.Voice` | | Video volume | `input[type="range"]` (`data-target="video"`) | `set-volume` | `Volume.Video` | | Text speed | `input[type="range"]` (`1`–`50`) | `set-text-speed` | `TextSpeed` | | Auto play speed | `input[type="range"]` (`0`–`60`) | `set-auto-play-speed` | `AutoPlaySpeed` | | Language | `select[data-action="set-language"]` | `set-language` | `Language` | | Resolution | `select[data-action="set-resolution"]` | `set-resolution` | `Resolution` | Notes on specific controls: - Volume sliders range from `0.0` (muted) to `1.0` (full). Their handler applies the new volume to the matching media players immediately and saves the value into the `Volume` preference object. - Text speed ranges from `1` (fastest) to `50` (slowest). Lower values display dialog faster. - Auto play speed ranges from `0` to `60` seconds. The maximum allowed value is clamped to the [`MaxAutoPlaySpeed`](/v2/configuration-options/player-preferences) setting, and on mount the screen sets `MaxAutoPlaySpeed` from the slider's `max` attribute. - Language is a dropdown listing every language present in the loaded script. Selecting one updates the `Language` preference and re-localizes the UI and game immediately. > [!TIP] > The label icons next to the Language and Resolution dropdowns carry a `data-select` attribute. Clicking the label focuses and opens the corresponding `<select>`, which makes the custom-styled dropdowns easier to use. ## Content Areas The component exposes the following named content areas (via `[data-content="…"]`). | Name | Selector | Description | | :--- | :--- | :--- | | `audio-settings` | `[data-content="audio-settings"]` | Container for the audio volume sliders. On iOS this is replaced with the `iOSAudioWarning` message. | | `language-settings` | `[data-content="language-settings"]` | The whole language section. Removed when `MultiLanguage` is `false`. | | `wrapper` | `[data-content="wrapper"]` | Holds the language `<select>` that is generated for multi-language games. | | `language-selector` | `[data-content="language-selector"]` | The generated language `<select>` element. | | `auto-play-speed-controller` | `[data-content="auto-play-speed-controller"]` | The auto-play speed range input. | > [!WARNING] > On iOS the individual audio sliders cannot work because the device controls volume through the system, so the audio area is replaced with the `iOSAudioWarning` string instead of the sliders. ## Desktop (Electron) Resolution The resolution dropdown is only active on desktop builds. When the desktop bridge is available, the screen requests the window's size constraints and, if the window is not freely resizable (because [`ForceAspectRatio`](../configuration-options/game-configuration/) is set to `Global`), populates the dropdown with valid windowed sizes plus a full-screen option. Choosing an option resizes the window and stores the chosen value in the `Resolution` preference. If the window is freely resizable, the resolution section is hidden. On the web, the `data-platform="desktop"` block is removed entirely. ```javascript // Default resolution used by desktop builds monogatari.preferences({ 'Resolution': '1280x720' }); ``` > [!NOTE] > The `Resolution` preference and this dropdown only affect Electron / Electrobun desktop builds. They have no effect on web-deployed games. ## Localization The screen uses `data-string` attributes for translatable text: | String Key | Default | Description | | :--- | :--- | :--- | | `Settings` | "Settings" | Screen title | | `Audio` | "Audio" | Audio section heading | | `Music` | "Music Volume" | Music slider label | | `Sound` | "Sound Volume" | Sound slider label | | `Voice` | "Voice Volume" | Voice slider label | | `Video` | "Video Volume" | Video slider label | | `TextSpeed` | "Text Speed" | Text speed section heading | | `AutoPlaySpeed` | "Autoplay Speed" | Auto-play section heading | | `Language` | "Language" | Language section heading | | `Resolution` | "Resolution" | Resolution section heading | | `iOSAudioWarning` | "Audio settings are not supported on iOS" | Shown in place of the sliders on iOS | | `Windowed` | "Windowed" | Prefix for windowed resolution options (desktop) | | `FullScreen` | "Full Screen" | Full-screen resolution option (desktop) | ## Styling The settings-screen can be styled with CSS against its real selectors: ```css / The screen itself / settings-screen { / Your styles / } / Only when the screen is open / settings-screen.active { / Visible state / } / Audio section / settings-screen [data-content="audio-settings"] { / Volume sliders container / } / Range inputs and selects / settings-screen input, settings-screen select { margin: 2rem; background-color: transparent; } / The two settings columns / settings-screen .settings { display: flex; flex-direction: column; gap: 1rem; } / Resolution section (desktop only) / settings-screen [data-settings="resolution"] { / Resolution dropdown container / } ``` ## Customizing ### Restyle a section Each settings group is a `data-settings="…"` block, and a few have named `data-content` regions. Target them directly to restyle or rearrange the screen: ```css / The audio sliders block / settings-screen [data-content="audio-settings"] { / Your styles / } / The text speed block / settings-screen [data-settings="text-speed"] { / Your styles / } / The auto-play block (the slider has its own content name) / settings-screen [data-content="auto-play-speed-controller"] { / Your styles / } ``` ### Hide a control To remove a control entirely, override the structure with the [`template()`](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure) function and drop the `data-settings` block you don't want. For example, to ship a game with no language picker, leave out the `data-settings="language"` / `data-content="language-settings"` block. (Keeping the [`MultiLanguage`](/v2/configuration-options/game-configuration/internationalization) setting `false` already removes that block at runtime, so you only need a custom template for controls that have no setting to disable them.) > [!NOTE] > If you change the structure, keep the `data-action` attributes (`set-volume`, `set-text-speed`, `set-auto-play-speed`, `set-language`, `set-resolution`) on the controls you keep, since those are what wire each control to its preference. ## Related - [Player Preferences](/v2/configuration-options/player-preferences) - The values these controls read and write - [Internationalization](/v2/configuration-options/game-configuration/internationalization) - Enables the language dropdown - [Save Screen](/v2/components/save-screen) - Where players store their progress - [Load Screen](/v2/components/load-screen) - Where players resume their progress --- # Type Writer > Animated text rendering that reveals characters one at a time, with inline effects, pauses and speed changes. Source: https://monogatari.io/v2/components/type-writer Section: Documentation ## Description ```markup <type-writer></type-writer> ``` The type-writer component handles animated text display, revealing characters one at a time with support for inline effects, pauses, and speed changes. It is used by the [text-box](/v2/components/text-box) and [centered-dialog](/v2/components/centered-dialog) components. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/type-writer](https://github.com/Monogatari/Monogatari/tree/develop/src/components/type-writer) ## Properties | Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | `string` | `string \| false` | `false` | The text to display | | `typeSpeed` | `number` | User preference | Typing speed in milliseconds per character | | `loop` | `boolean \| number` | `false` | Whether to loop the animation, or number of loops | | `showCursor` | `boolean` | `false` | Show a blinking cursor during typing | | `hideCursorOnEnd` | `boolean` | `false` | Hide cursor when typing completes | | `delay` | `number` | `undefined` | Delay before starting animation (ms) | | `start` | `boolean` | `false` | Auto-start animation on mount | ## Methods ### `setContent(text: string, animate?: boolean): void` The primary API for displaying text. Sets the content and optionally animates it. ```javascript const typeWriter = document.querySelector('type-writer'); // With animation typeWriter.setContent('Hello, world!', true); // Without animation (instant display) typeWriter.setContent('Hello, world!', false); ``` ### `finish(instant?: boolean): void` Complete the typing animation immediately. ```javascript const typeWriter = document.querySelector('type-writer'); // Rush through remaining text at max speed typeWriter.finish(false); // Instantly show all text typeWriter.finish(true); ``` ### `stop(): void` Stop the typing animation at its current position. ```javascript typeWriter.stop(); ``` ### `start(): void` Resume a stopped animation. ```javascript typeWriter.start(); ``` ### `destroy(): void` Stop and clean up the animation. ```javascript typeWriter.destroy(); ``` ## Action Markers The type-writer supports inline action markers that control the animation. These are stripped from the final displayed text. ### Pause Pause the animation for a specified duration: ```javascript 'Hello...{pause:1000} How are you?' // Pause for 1 second 'Hello...{pause 1000} How are you?' // Alternative syntax ``` ### Speed Change the typing speed as a percentage (100 = normal): ```javascript 'Normal speed. {speed:50}Half speed. {speed:200}Double speed!' ``` ### Enclosed Effects Apply visual effects to portions of text using `{effect}text{/effect}` syntax: #### Animation Effects | Effect | Description | | :--- | :--- | | `{shake}` | Shaking text | | `{shake-hard}` | Intense shaking | | `{shake-slow}` | Slow shaking | | `{shake-little}` | Subtle shaking | | `{shake-horizontal}` | Horizontal shaking only | | `{shake-vertical}` | Vertical shaking only | | `{wave}` | Wavy animation | | `{wave-slow}` | Slow wave | | `{wave-fast}` | Fast wave | | `{fade}` | Fading in/out | | `{fade-slow}` | Slow fade | | `{blur}` | Blurred text | | `{scale}` | Scaling animation | | `{scale-bounce}` | Bouncy scaling | | `{slide-up}` | Sliding up | | `{slide-down}` | Sliding down | | `{glitch}` | Glitch effect | | `{glitch-hard}` | Intense glitch | | `{glitch-slow}` | Slow glitch | | `{flicker}` | Flickering | #### Style Effects | Effect | Description | | :--- | :--- | | `{bold}` | Bold text | | `{italic}` | Italic text | | `{big}` | Larger text | | `{small}` | Smaller text | | `{strike}` | Strikethrough | | `{redacted}` | Redacted/censored | | `{invisible-ink}` | Hidden until hover | | `{handwriting}` | Handwritten style | | `{impact}` | Impact emphasis | #### Emotion Effects | Effect | Description | | :--- | :--- | | `{angry}` | Angry styling (red, shaking) | | `{scared}` | Scared styling | | `{happy}` | Happy styling | | `{sad}` | Sad styling | | `{mysterious}` | Mysterious styling | | `{excited}` | Excited styling | | `{whisper}` | Whisper (small, faded) | | `{shout}` | Shouting (large, bold) | | `{dizzy}` | Dizzy effect | | `{dreamy}` | Dreamy styling | | `{robotic}` | Robotic/monospace | | `{static}` | Static noise effect | | `{rainbow}` | Rainbow colors | | `{glow}` | Glowing text | #### Example ```javascript 'y I am {angry}so frustrated{/angry}! {pause:500}{whisper}But it will be okay{/whisper}.' ``` ## Registering Custom Actions You can register custom actions using the static `action` method: ```javascript // Number action (like pause/speed) TypeWriter.action({ name: 'myaction', type: 'number', action: function(number) { console.log('Action with value:', number); } }); // Usage: {myaction:500} // Enclosed action (wraps text) TypeWriter.action({ name: 'highlight', type: 'enclosed', action: function() { // Effects are applied via CSS using the action name as a class } }); // Usage: {highlight}text{/highlight} ``` ### Action Types | Type | Syntax | Description | | :--- | :--- | :--- | | `number` | `{name:N}` or `{name N}` | Action with a numeric parameter | | `enclosed` | `{name}...{/name}` | Wraps text, applies CSS class | | `instance` | `{name/}` | Self-closing, single-point action | ## Static Methods ### `TypeWriter.actions(): TypeWriterActions` Get all registered actions. ### `TypeWriter.action(action: TypeWriterAction): TypeWriterAction` Register a new action or get an existing one. ### `TypeWriter.stripActionMarkers(str: string): string` Remove all action markers from a string, returning plain text. ```javascript const clean = TypeWriter.stripActionMarkers('Hello {pause:500} {shake}world{/shake}!'); // Returns: 'Hello world!' ``` ### `TypeWriter.configuration(config?: object): object` Get or set the component configuration. ## Events The type-writer triggers engine events during its lifecycle: | Event | Description | | :--- | :--- | | `didStartTyping` | Fired when typing animation begins | | `didFinishTyping` | Fired when typing animation completes | ## Global State | Global | Description | | :--- | :--- | | `finished_typing` | `true` when typing is complete, `false` during animation | ## Styling Each character is wrapped in a `<type-character>` element: ```css / Individual characters / type-character { / Base character styles / } / Cursor (when enabled) / type-character.cursor::after { content: '|'; animation: blink 1s infinite; } / Effect classes are applied to type-character elements / type-character[data-special="shake"] { animation: shake 0.5s infinite; } ``` ## Related - [Text Box](/v2/components/text-box) - Contains type-writer for dialog display - [Centered Dialog](/v2/components/centered-dialog) - Contains type-writer for centered text - [Dialog Action](/v2/script-actions/dialogs) - Uses type-writer for text animation --- # Dialog Log > A scrollable history of every dialog shown during play, opened from the Log button in the quick menu. Source: https://monogatari.io/v2/components/dialog-log Section: Documentation ## Description ```markup <dialog-log></dialog-log> ``` The dialog-log component provides a scrollable history of all dialogs displayed during gameplay. Players can access it to review past conversations they may have missed or want to re-read. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/dialog-log](https://github.com/Monogatari/Monogatari/tree/develop/src/components/dialog-log) ## Usage The dialog-log automatically appears in the quick menu as a "Log" button. Clicking it toggles the dialog log modal. ## Structure ```html <dialog-log class="modal" data-component="dialog-log"> <div class="modal__content"> <div data-content="log">  <div class="text--center padded" data-string="NoDialogsAvailable" data-content="placeholder"> No dialogs available. Dialogs will appear here as they show up. </div> </div> <button data-string="Close" data-action="dialog-log">Close</button> </div> </dialog-log> ``` ## Dialog Entry Structure Each dialog entry is rendered as: ```html  <div data-spoke="character_id" class="named"> <span style="color:#ff0000;">Character Name </span> <p>The dialog text here.</p> </div>  <div data-spoke="_narrator" class="unnamed"> <p>Narrator text here.</p> </div> ``` ## State | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `active` | `boolean` | `false` | Whether the dialog log modal is currently visible | ## Methods ### `write(entry: DialogEntry): void` Add a new dialog entry to the log. This is called automatically by the [Dialog action](/v2/script-actions/dialogs). ```typescript interface DialogEntry { id: string; // Character ID or '_narrator' character: Character; // Character object with name/color dialog: string; // The dialog text } ``` ### `pop(): void` Remove the last dialog entry from the log. Used during rollback/revert operations. ## Events The dialog-log registers a listener for the `dialog-log` action, which toggles its visibility: ```javascript // Toggle dialog log programmatically monogatari.trigger('dialog-log'); ``` ## Quick Menu Integration During setup, the dialog-log automatically adds a "Log" button to the quick menu: ```javascript // This happens automatically during component setup quickMenu.addButtonAfter('Hide', { string: 'Log', icon: 'far fa-comments', data: { action: 'dialog-log' } }); ``` ## Styling ```css /* Modal container / dialog-log { / Modal base styles inherited from .modal class / } / Active state / dialog-log.modal--active { display: flex; / Or your preferred display method / } / Log content area / dialog-log [data-content="log"] { overflow-y: auto; max-height: 60vh; } / Character dialog entry / dialog-log [data-spoke].named { / Named character styling / } dialog-log [data-spoke].named span { / Character name styling (color is inline from character definition) / } / Narrator dialog entry / dialog-log [data-spoke].unnamed { / Narrator styling / } / Placeholder when empty / dialog-log [data-content="placeholder"] { text-align: center; padding: 2em; opacity: 0.7; } / Close button / dialog-log button[data-action="dialog-log"] { / Close button styling / } ``` ## Reset Behavior When the game is reset, the dialog log is cleared and the placeholder message is restored: ```javascript // Automatically called on game reset dialogLog.onReset(); ``` ## Localization The component uses data-string attributes for translatable text: | String Key | Default | Description | | :--- | :--- | :--- | | `NoDialogsAvailable` | "No dialogs available..." | Placeholder text | | `Close` | "Close" | Close button text | ## Related - [Dialog Action](/v2/script-actions/dialogs) - Populates the dialog log - [Text Box](/v2/components/text-box) - Displays current dialog - [Quick Menu](/v2/components/quick-menu) - Contains the Log button --- # Centered Dialog > A floating dialog box centered on the screen, shown when a line begins with the `centered` keyword. Source: https://monogatari.io/v2/components/centered-dialog Section: Documentation ## Description ```markup <centered-dialog></centered-dialog> ``` The centered-dialog component displays text in a floating box centered on the screen. It is used when dialogs begin with the `centered` keyword. While a centered dialog is visible, the regular [text-box](/v2/components/text-box) is hidden. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/centered-dialog](https://github.com/Monogatari/Monogatari/tree/develop/src/components/centered-dialog) ## Usage Centered dialogs are created automatically by the [Dialog action](/v2/script-actions/dialogs) when the `centered` keyword is used: ```javascript 'centered This is a dramatic moment.' 'centered::dramatic An even more dramatic moment!' ``` ## Structure The centered-dialog component renders a simple structure with a type-writer for animated text: ```html <centered-dialog data-component="centered-dialog"> <type-writer data-content="wrapper"></type-writer> </centered-dialog> ``` ## Content Areas | Name | Selector | Description | | :--- | :--- | :--- | | `wrapper` | `[data-content="wrapper"]` | The type-writer element containing the centered text | ## Lifecycle 1. When `centered` dialog is triggered, a new `<centered-dialog>` element is created 2. The regular `<text-box>` is hidden 3. The centered dialog is appended to the game screen 4. When the player proceeds, the centered dialog is removed and text-box is restored ## Custom Classes Custom CSS classes can be applied to the centered-dialog using the dialog syntax: ```javascript 'centered::highlight Important announcement!' 'centered::dramatic|urgent Critical message!' ``` Classes are specified after double colons and separated by `|` (pipe). ## Styling ```css / Main container / centered-dialog { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); / Add your styling / } / Animated entrance / centered-dialog.animated { animation: fadeIn 0.3s ease-out; } / Custom class example / centered-dialog.dramatic { font-size: 2em; text-shadow: 0 0 20px rgba(255, 255, 255, 0.8); } / The text wrapper / centered-dialog [data-content="wrapper"] { / Type-writer container styles / } ``` ## Animation Settings The typing animation for centered dialogs can be controlled via the `CenteredTypeAnimation` setting: ```javascript // Enable/disable typing animation for centered dialogs monogatari.setting('CenteredTypeAnimation', true); // default monogatari.setting('CenteredTypeAnimation', false); // instant display ``` `CenteredTypeAnimation` is part of the `TypeAnimation` family of settings that control the typewriter animation. See [Game Configuration](/v2/configuration-options/game-configuration) for the full family. ## Methods The centered-dialog component inherits from the base Component class. The type-writer inside provides all text animation functionality. ### Accessing the Type Writer ```javascript const centeredDialog = document.querySelector('centered-dialog'); const typeWriter = centeredDialog.content('wrapper').get(0); // Force finish animation typeWriter.finish(true); ``` ## Related - [Text Box](/v2/components/text-box) - The regular dialog display component - [Type Writer](/v2/components/type-writer) - Handles text animation - [Dialog Action](/v2/script-actions/dialogs) - Controls when centered dialogs appear --- # Translations > Help translate Monogatari's interface into more languages. Source: https://monogatari.io/v2/contribute/translations Section: Documentation Beyond translating your own game's content, you can help translate Monogatari's interface — the built-in buttons, labels and messages — into more languages. If you speak a language Monogatari doesn't support yet, your help is more than welcome! > [!NOTE] > This page is about contributing UI translations to the Monogatari engine itself. > To translate the content of your own game, see > [Internationalization](/v2/configuration-options/game-configuration/internationalization). ## Where the translations live Each language is a single TypeScript file under [`src/translations/`](https://github.com/Monogatari/Monogatari/tree/develop/src/translations) that exports a default object mapping string keys to their translated text: ```typescript // src/translations/English.ts export default { 'AdvanceHelp': 'To advance through the game, left-click or tap anywhere on the game screen or press the space key', 'Audio': 'Audio', 'AutoPlay': 'Auto', 'Back': 'Back', 'Cancel': 'Cancel', 'Close': 'Close', // ...one entry per interface string }; ``` The keys are fixed identifiers used throughout the engine — keep them exactly as they are. Only translate the values. ## Adding a new language 1. Copy `English.ts` to a new file named after your language in its own script, e.g. `src/translations/Italiano.ts`. English is the most complete file, so it's the best starting point. 2. Translate every value, leaving the keys untouched: ```typescript // src/translations/Italiano.ts export default { 'AdvanceHelp': 'Per avanzare nel gioco, fai clic o tocca lo schermo, oppure premi la barra spaziatrice', 'Audio': 'Audio', 'AutoPlay': 'Auto', 'Back': 'Indietro', // ... }; ``` 3. Register the language in [`src/index.ts`](https://github.com/Monogatari/Monogatari/blob/develop/src/index.ts). Import your file, add it to `Monogatari._translations` keyed by the language's native name, and add its metadata — an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) and a flag emoji — to `Monogatari._languageMetadata`: ```typescript import italian from './translations/Italiano'; Monogatari._translations = { // ...existing languages 'Italiano': italian, }; Monogatari._languageMetadata = { // ...existing metadata 'Italiano': { code: 'it', icon: '🇮🇹', }, }; ``` 4. Open a pull request with your new translation file and the registration changes. > [!TIP] > If a string has no natural translation in your language, it's fine to keep the > English value — a partial translation is still a great contribution, and others can > fill in the gaps later. ## See also - [Internationalization](/v2/configuration-options/game-configuration/internationalization) — Translate your own game's content and offer a language-selection screen. - [Language Selection Screen](/v2/components/language-selection-screen) — The screen players use to pick a language. --- # Events > The engine events you can hook into with monogatari.on() to run your own code. Source: https://monogatari.io/v2/advanced-monogatari-development/events Section: Documentation Monogatari emits events at key moments of its lifecycle. You can listen for any of them with `monogatari.on ()` and run your own code — perfect for analytics, custom UI, debugging, or reacting to the player's progress. ```javascript // Run a function every time a save file finishes loading monogatari.on ('didLoadGame', () => { console.log ('A game was loaded!'); }); ``` By convention, events prefixed with `will` fire before* something happens, and events prefixed with `did` fire after it. > [!TIP] > Register your listeners before calling `monogatari.init ()`, so that early lifecycle > events like `willInit` and `didSetup` aren't missed. [TOC] ## Initialization, Setup & Binding Fired as the engine boots. Initialization wraps the setup and binding steps, so they fire in this order: | Event | When it fires | | :--- | :--- | | `willInit` | Before initialization begins. | | `willSetup` | Before the engine runs the `setup ()` step of its actions and components. | | `didSetup` | After setup completes. | | `willBind` | Before the engine runs the `bind ()` step (wiring up DOM listeners). | | `didBind` | After binding completes. | | `didInit` | After initialization finishes — the engine is ready and the first screen is shown. | Because these events fire during `monogatari.init ()`, you have to register their listeners before you call it — otherwise they'll have already fired by the time your listener exists: ```javascript // In main.js, before monogatari.init () monogatari.on ('willInit', () => { console.log ('Monogatari is about to initialize'); }); monogatari.on ('didInit', () => { console.log ('Monogatari is ready and the first screen is showing'); }); monogatari.init ('#monogatari'); ``` ## Asset Preloading Fired while Monogatari preloads the assets declared in your game (see [Asset Preloading](/v2/configuration-options/game-configuration/asset-preloading)). | Event | When it fires | | :--- | :--- | | `willPreloadAssets` | Before preloading begins. | | `assetQueued` | Each time an asset is added to the preload queue. Useful for computing a total for a custom progress bar. | | `assetLoaded` | Each time a single asset finishes loading. The [Loading Screen](/v2/components/loading-screen) listens for this to advance its progress bar. | | `didPreloadAssets` | After every queued asset has loaded. | ## Actions Fired around every [action](/v2/building-blocks/actions) as the story plays forward and backward. | Event | When it fires | | :--- | :--- | | `willRunAction` | Before an action applies. | | `didRunAction` | After an action has applied. | | `willRevertAction` | Before an action is reverted (when the player rolls back). | | `didRevertAction` | After an action has been reverted. | ## Game State Fired whenever the in-game state — the stack of applied actions and the current step — changes. | Event | When it fires | | :--- | :--- | | `willUpdateState` | Before the engine updates its game state. | | `didUpdateState` | After the game state has been updated. | ## Configuration Fired when engine configuration changes at runtime via `monogatari.configuration ()`. | Event | When it fires | | :--- | :--- | | `configurationWillUpdate` | Before a configuration object is updated. | | `configurationDidUpdate` | After a configuration object is updated. | | `configurationElementWillUpdate` | Before a single configuration element changes. | | `configurationElementDidUpdate` | After a single configuration element changes. | ## Localization Fired when the interface is localized to a language (see [Internationalization](/v2/configuration-options/game-configuration/internationalization)). | Event | When it fires | | :--- | :--- | | `willLocalize` | Before the UI strings are swapped to the selected language. | | `didLocalize` | After the UI has been localized. | ## Components | Event | When it fires | | :--- | :--- | | `componentDidMount` | After a [component](/v2/building-blocks/components) is mounted to the DOM. | | `componentDidUnmount` | After a component is removed from the DOM. | ## Typing Fired by the [Type Writer](/v2/components/type-writer) as dialog text animates. | Event | When it fires | | :--- | :--- | | `didStartTyping` | When the typewriter starts revealing a line of dialog. | | `didFinishTyping` | When a line of dialog finishes — whether the animation completed on its own, the player clicked to skip it, or typewriter animation is disabled. | ## Save File Loading | Event | When it fires | | :--- | :--- | | `willLoadGame` | After the player chooses to load a save, but before loading finishes. | | `didLoadGame` | After a save has fully loaded and all storage variables are set, but before anything is drawn and before the player regains control. | ## Responding to events A common pattern is reacting to the typewriter or to the player's progress: ```javascript monogatari.on ('didFinishTyping', () => { // e.g. show a custom "click to continue" indicator }); monogatari.on ('didRunAction', () => { // e.g. update an analytics counter for statements seen }); ``` > [!NOTE] > This list reflects the events the engine currently emits. The `will…` / `did…` > naming is the rule of thumb: hook `will…` to act just before something happens, > `did…` to act just after. --- # Translations > Add or override Monogatari's interface strings for your game, in any language. Source: https://monogatari.io/v2/advanced-monogatari-development/translations Section: Documentation Monogatari's interface — buttons, labels and messages — ships translated into many languages. For your own game you can add a language, override individual strings, or tweak the wording, all from your game's JavaScript with no engine changes. > [!NOTE] > This page is about UI strings in your game. To translate the content of your > story across languages, see [Internationalization](/v2/configuration-options/game-configuration/internationalization). > To contribute a translation back to Monogatari itself, see > [Contributing Translations](/v2/contribute/translations). ## How UI strings work Every translatable piece of interface text has a key (e.g. `Save`, `Settings`, `Loading`). The engine looks up that key for the current language and shows the matching string. In markup, an element with `data-string="Save"` is filled with the translation of `Save` automatically — so the same interface works in every language. ## Add or override strings Call `monogatari.translation()` with a language name and an object of `key: value` strings. It merges into that language, so you can override built-in strings or add new ones (handy for custom buttons and components): ```javascript // Override a built-in string and add a custom one (English) monogatari.translation ('English', { 'Quit': 'Exit', 'Stats': 'Statistics' // a custom key your own button/component uses }); // Provide strings for a whole language monogatari.translation ('Italiano', { 'Save': 'Salva', 'Load': 'Carica', 'Settings': 'Impostazioni' }); ``` Then reference a custom key from your own markup with `data-string`: ```html <span data-string="Stats">Statistics</span> ``` ## Offering multiple languages To let players choose a language, enable multi-language mode and Monogatari shows a [language-selection screen](/v2/components/language-selection-screen) before the game starts: ```javascript monogatari.settings ({ 'MultiLanguage': true }); ``` See [Internationalization](/v2/configuration-options/game-configuration/internationalization) for the full multi-language setup, including translating your story's dialog. ## See also - [Internationalization](/v2/configuration-options/game-configuration/internationalization) — Multi-language games and the language-selection screen. - [Contributing Translations](/v2/contribute/translations) — Add a language to Monogatari itself. - [HTML Data Attributes](/v2/style-and-design/data-attributes) — The `data-string` mechanism. --- # Components Source: https://monogatari.io/v2/advanced-monogatari-development/components Section: Documentation This page has been moved to [Building Blocks: Components](../building-blocks/components/). --- # Actions Source: https://monogatari.io/v2/advanced-monogatari-development/actions Section: Documentation This page has been moved to [Building Blocks: Actions](../building-blocks/actions/). --- # Core Libraries > >- Source: https://monogatari.io/v2/advanced-monogatari-development/core-libraries Section: Documentation On the very core of Monogatari, you'll find it has been built around the [Aegis Framework](https://aegisframework.com/) libraries. These libraries are used both for functionality and styling so learning more about them will allow you to create even more amazing things! ## [Artemis: JavaScript Library](https://gitlab.com/AegisFramework/Artemis) Artemis is used for DOM manipulation, storage, HTTP requests handling, text transformations and more! ## [Kayros: CSS Library](https://gitlab.com/AegisFramework/Kayros) Kayros is the very base of Monogatari's style and look! ## [Pandora: Web Components Library](https://gitlab.com/AegisFramework/pandora/) Pandora is what allows monogatari to have self contained, custom HTML elements and allows them to have custom functionality. --- # Advanced: Monogatari Development Source: https://monogatari.io/v2/advanced-monogatari-development Section: Documentation Guides in this section: - [Actions](/v2/advanced-monogatari-development/actions) - [Components](/v2/advanced-monogatari-development/components) - [Translations](/v2/advanced-monogatari-development/translations) - [Events](/v2/advanced-monogatari-development/events) --- # Web > Build your game for the web and publish it anywhere — itch.io, a static host, or your own server. Source: https://monogatari.io/v2/releasing-your-game/web Section: Documentation Releasing on the web is the fastest way to get your game in front of players: it runs instantly in any modern browser, on desktop and mobile alike. Here's how to prepare, build and publish it. ## 1. Fill in your metadata Open `index.html`. Near the top is a block of `<meta>` tags that set your game's title, description, social-sharing preview and icons. Filling them in isn't required for the game to run, but it makes a big difference to how your game looks in search results and when shared. At minimum, set: ```html <title>Your Game Title</title> <meta name="description" content="A short, catchy description of your game."> <meta name="author" content="Your Name">  <meta property="og:title" content="Your Game Title"> <meta property="og:description" content="A short, catchy description."> <meta property="og:image" content="https://yourdomain.com/preview.png"> <meta property="og:url" content="https://yourdomain.com"> <meta name="theme-color" content="#5bcaff"> ``` ## 2. Add your icons The template ships placeholder icons in `assets/icons/` and a `favicon.ico` at the project root. Replace them with your own — keep the same file names and sizes — so your game looks right in browser tabs, on home screens and when installed. A generator like [RealFaviconGenerator](https://realfavicongenerator.net/) can produce every size at once. ## 3. Optimize your assets Large images and audio are the main thing that slows a game down. Compress your images (tools like [Squoosh](https://squoosh.app/) work well) and keep audio at a reasonable bitrate. Combined with Monogatari's [asset preloading](/v2/configuration-options/game-configuration/asset-preloading), this keeps load times short even on slow connections. ## 4. Build Produce a clean, production copy of your game: ```bash bun run build:web ``` This writes everything players need into the `build/web/` folder — your assets, the engine, your scripts and styles, the service worker and the manifest. That folder is your game. ## 5. Publish Upload the contents of `build/web/` wherever you want to host it: - [itch.io](https://itch.io) — the go-to home for visual novels. Zip the contents of `build/web/`, upload it as an HTML5 project, and tick "This file will be played in the browser" (itch uses `index.html` as the entry point). - Static hosts — [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), [Cloudflare Pages](https://pages.cloudflare.com/) and [GitHub Pages](https://pages.github.com/) all serve a folder of files for free over HTTPS. - Your own server — any web server works; the template includes an `.htaccess` for Apache. > [!TIP] > Serve your game over HTTPS (every host above does). It's required for the service > worker that powers [offline play and asset caching](/v2/configuration-options/game-configuration/asset-preloading). ## Bonus: an installable app Because the build includes a `manifest.json` and a service worker, your web release is already a Progressive Web App — players can install it to their home screen and play it offline, just like a native app. See [Mobile](/v2/releasing-your-game/mobile) to make the most of it. --- # Mobile > Reach phones and tablets — installable as an app, with offline play. Source: https://monogatari.io/v2/releasing-your-game/mobile Section: Documentation Your Monogatari game already runs great on phones and tablets — the interface is responsive out of the box. There are two ways to deliver it. ## The easy way: install as an app (PWA) Because your [web release](/v2/releasing-your-game/web) includes a `manifest.json` and a service worker, it's already a Progressive Web App. With no extra tooling, players can: - Add it to their home screen — it gets its own icon and launches full-screen, like a native app. ([How to add a website to the home screen](https://www.howtogeek.com/196087/how-to-add-websites-to-the-home-screen-on-any-smartphone-or-tablet/).) - Play offline — once your [service worker cache](/v2/configuration-options/game-configuration/asset-preloading) is set up, the game works without a connection. - See a splash screen on launch, using the icons and colors from your `manifest.json`. To make this shine, fill in the key `manifest.json` fields: ```json { "short_name": "My Game", "name": "My Visual Novel", "background_color": "#F7F7F7", "theme_color": "#F7F7F7" } ``` For every available option, see the [Web App Manifest reference](https://developer.mozilla.org/en-US/docs/Web/Manifest). > [!TIP] > Encourage players to install your game — a home-screen icon and offline play make it > feel like a real mobile app, with nothing to download from a store. ## App-store distribution (advanced) To ship to the Google Play Store or Apple App Store, wrap your built game in a native shell with a tool like [Capacitor](https://capacitorjs.com/) or [Apache Cordova](https://cordova.apache.org/). The approach is the same for both: build your game for the web with `bun run build:web`, point the wrapper at the contents of `build/web/` as its web assets, then follow that tool's instructions to produce an Android or iOS package. > [!NOTE] > Publishing to either store requires a developer account — Google's is a one-time fee, > Apple's is annual — and, for iOS, a Mac to build on. --- # Desktop App > Package your game as a standalone Windows, macOS or Linux application. Source: https://monogatari.io/v2/releasing-your-game/desktop Section: Documentation Monogatari can package your game as a standalone desktop app. The template supports two toolchains out of the box — pick whichever you prefer: - [Electron](https://www.electronjs.org/) — the long-established option, built with `electron-builder`. - [Electrobun](https://electrobun.dev/) — a newer, lighter alternative. ## Install the build tools Desktop builds need the template's dependencies installed once: ```bash bun install ``` ## Electron Build for a specific platform: ```bash bun run build:windows # Windows installer bun run build:mac # macOS app bun run build:linux # Linux AppImage ``` The finished installers land in the `build/electron/` folder, ready to distribute. > [!WARNING] > Since macOS Catalina, Apple [requires apps to be notarized](https://developer.apple.com/news/?id=12232019a). Notarizing requires a Mac and an [Apple Developer](https://developer.apple.com/programs/) membership (an annual fee). If you'd like to distribute on macOS but can't meet those requirements, reach out — we may be able to notarize your app for you. ## Electrobun To build with Electrobun instead: ```bash bun run build:electrobun ``` Or run it in development to preview the desktop app as you work: ```bash bun run start:electrobun ``` > [!NOTE] > Configure your app's name, identifier and icons in the template's `package.json` > (the `build` block, for Electron) and `electrobun.config.ts` (for Electrobun). --- # Chrome App > Chrome Apps are discontinued — release your game as a website instead. Source: https://monogatari.io/v2/releasing-your-game/chrome Section: Documentation Google [discontinued apps on the Chrome Web Store](https://blog.chromium.org/2020/01/moving-forward-from-chrome-apps.html), so this is no longer a supported way to release your game. Release it as a [web](/v2/releasing-your-game/web) game instead — it runs in Chrome and every other modern browser, and can still be [installed to a device](/v2/releasing-your-game/mobile) as a Progressive Web App. --- # Releasing Your Game Source: https://monogatari.io/v2/releasing-your-game Section: Documentation Because your Monogatari game is a website, one project ships everywhere — the web, desktop and mobile — usually from the very same files. Pick the targets that fit your audience: | Target | Best for | Build command | | :--- | :--- | :--- | | [Web](/v2/releasing-your-game/web) | The widest reach — playable instantly in any browser, including on [itch.io](https://itch.io). | `bun run build:web` | | [Desktop](/v2/releasing-your-game/desktop) | Standalone Windows, macOS and Linux apps. | `bun run build:windows` / `build:mac` / `build:linux` | | [Mobile](/v2/releasing-your-game/mobile) | Phones and tablets — installable as an app, with offline play. | (PWA — no build needed) | Most games start with a [web release](/v2/releasing-your-game/web): it's the quickest, reaches the most players, and doubles as the basis for the mobile (PWA) experience. > [!NOTE] > Looking for the old Chrome App target? Google [discontinued it](/v2/releasing-your-game/chrome) — release as a [web](/v2/releasing-your-game/web) game instead. --- # Image Menus Source: https://monogatari.io/v2/style-and-design/image-menus Section: Documentation Many use Image Menus for their interfaces, however, I really discourage this in Monogatari. It's fairly easy to do it as you can see in [this tutorial](http://www.w3schools.com/tags/tag_map.asp) however using image maps is not good for the responsiveness and since we want everyone to be able to enjoy our game, I really encourage you to do everything using HTML and CSS. Sure, the buttons, headers, texts etc. can have background images, but try to avoid using them as the main interface. --- # Icons > Use Font Awesome icons anywhere in your game — in menus, buttons and dialog. Source: https://monogatari.io/v2/style-and-design/icons Section: Documentation Monogatari ships with [Font Awesome](https://fontawesome.com/) (v7), so thousands of icons are available without installing anything. They're already used throughout the default interface — the quick-menu buttons, the help screen, and more. ## Using an icon Add a `<span>` (or `<i>`) with the icon's classes. Each icon has a style prefix and a name: ```html <span class="fas fa-floppy-disk"></span>  <span class="far fa-floppy-disk"></span>  <span class="fab fa-github"></span>  ``` | Prefix | Style | | :--- | :--- | | `fas` | Solid | | `far` | Regular (outline) | | `fab` | Brands (logos) | Browse and search every icon — with the exact class to copy — on the [Font Awesome icon gallery](https://fontawesome.com/icons). ## In menu buttons Anywhere you give a Monogatari button an icon (a [quick menu](/v2/components/quick-menu) or [main menu](/v2/components/main-menu) button), you pass the same classes: ```javascript monogatari.component ('quick-menu').addButton ({ string: 'Stats', icon: 'fas fa-chart-simple', data: { action: 'show-stats' } }); ``` ## In dialog and custom HTML Because your game is a web page, you can drop an icon into any HTML you write — a [message](/v2/script-actions/message), a custom [component](/v2/building-blocks/components), or styled dialog: ```html <p>Press <span class="fas fa-arrow-right"></span> to continue.</p> ``` > [!NOTE] > Older Monogatari versions shipped Font Awesome 4/5, where some icons had different > names (for example `fa-save` is now `fa-floppy-disk`). If an icon from an old tutorial > doesn't show up, search its current name on the Font Awesome site. --- # HTML Data Attributes > The data-* attributes Monogatari uses to wire up the interface, and how to use them when customizing. Source: https://monogatari.io/v2/style-and-design/data-attributes Section: Documentation ## Overview Monogatari's interface is driven by `data-` attributes rather than fixed markup. The engine finds elements by their data attributes, so as long as you keep the right attributes in place you can restructure the HTML of any [component](/v2/components) freely and everything keeps working. ## General attributes | Attribute | Purpose | | :--- | :--- | | `data-component` | Marks a custom element as a Monogatari component, e.g. `data-component="text-box"`. The engine and your CSS target components through it. | | `data-content` | Marks a region inside a component that the component reads or writes — e.g. `data-content="text"` for the dialog text. This is the main hook you'll use when [changing a component's structure](/v2/building-blocks/components/built-in-functions). | | `data-screen` | Marks a full-screen component and names the screen, e.g. `data-screen="settings"`. | | `data-action` | Declares an interactive control; clicks are handled centrally by the engine. See the table below. | | `data-open` | Names the screen a `data-action="open-screen"` control opens (e.g. `data-open="settings"`). | | `data-ui` | Marks a part of the user interface the engine manipulates. | | `data-target` | Targets a specific element for an action — for example, which audio channel a `set-volume` control changes. | | `data-string` | Marks text that is replaced with the matching [translation](/v2/advanced-monogatari-development/translations) for the current language. | | `data-background` | Set an image URL on it and the engine applies it as the element's background. | | `data-close` | Closes another element, referenced by its name. | | `data-jump` | On a choice, the label the game jumps to when the choice is clicked. | ## `data-action` values `data-action` turns an element into a control. The most common values: | Value | What it does | | :--- | :--- | | `open-screen` | Opens the screen named in the neighbouring `data-open` and closes the others. | | `back` | While playing, rolls back to the previous statement; on a screen, returns to the previous screen. | | `close` | Closes the element named in the neighbouring `data-close`. | | `close-video` | Closes the video element. | | `set-language` | Sets the interface language (used by the [language selection](/v2/components/language-selection-screen) and [settings](/v2/components/settings-screen) screens). | | `set-volume` | Changes the volume of the channel named in `data-target` (`music`, `sound`, `voice`, `video`). | | `jump` | Jumps to the label named in the element's `data-jump`. | > [!NOTE] > Older versions used `data-menu` and `data-ui="who"` / `"say"` to mark screens and > dialog regions. Current components use `data-screen` for screens and > `data-content="…"` for their internal regions — for example the text box exposes > `data-content="text"`, `data-content="character-name"`, and > `data-content="character-expression"`. ## Text effects (`data-effect-`) When a line of dialog uses an inline effect (see the [Type Writer](/v2/components/type-writer)), the typewriter wraps that span in a `data-effect-` attribute your CSS can target. The family includes emphasis (`data-effect-bold`, `data-effect-italic`, `data-effect-big`, `data-effect-small`), motion (`data-effect-shake`, `data-effect-wave`, `data-effect-slide-up`, `data-effect-scale`), mood (`data-effect-angry`, `data-effect-happy`, `data-effect-sad`, `data-effect-excited`, `data-effect-scared`, `data-effect-dreamy`, `data-effect-mysterious`), and stylized looks (`data-effect-glitch`, `data-effect-rainbow`, `data-effect-glow`, `data-effect-redacted`, `data-effect-invisible-ink`, `data-effect-handwriting`, `data-effect-robotic`) — with `-slow` / `-hard` / `-fast` variants for several. ```css / Restyle the "glow" effect to match your game / [data-effect-glow] { text-shadow: 0 0 0.4em var(--color-primary); } ``` See the [Type Writer](/v2/components/type-writer) component for the full list of effects and how to use them in dialog. ## See also - [CSS Classes](/v2/style-and-design/classes) — The styling hooks that pair with these attributes. - [Components](/v2/components) — Each component documents its own `data-content` regions. - [Built-in Functions](/v2/building-blocks/components/built-in-functions) — How to change a component's HTML structure. --- # CSS Classes > The helper CSS classes Monogatari ships with for positioning and aligning interface elements. Source: https://monogatari.io/v2/style-and-design/classes Section: Documentation There are already some CSS classes declared to make your designing a little easier. As you may have already noticed, many are already used in the basic interface you get by default. ## Positioning | Class | Description | | :--- | :--- | | `center` | Positions the element in the horizontal center of the screen. | | `left` | Positions the element on the left side of the screen. | | `right` | Positions the element on the right side of the screen. | | `bottom` | Positions the element at the bottom of the screen. | | `middle` | Positions the element in the middle of the screen, vertically and horizontally. | ## Text alignment | Class | Description | | :--- | :--- | | `text--left` | Aligns the text content to the left. | | `text--center` | Aligns the text content to the center. | | `text--right` | Aligns the text content to the right. | | `text--justify` | Justifies the text content. | ## Layout | Class | Description | | :--- | :--- | | `horizontal` | Lays the content out in a horizontal row. | | `horizontal--left` / `horizontal--center` / `horizontal--right` | Align the items of a `horizontal` container to the start, center, or end. | | `vertical` | Lays the content out in a vertical column. | | `vertical--left` / `vertical--center` / `vertical--right` | Align the items of a `vertical` container to the start, center, or end. | ## Modals | Class | Description | | :--- | :--- | | `modal--active` | Applied to a modal element (such as the [dialog log](/v2/components/dialog-log)) to make it visible. | ## Common patterns These classes are meant to be combined. A few combinations you'll reach for often: A horizontal row of buttons, centered: ```html <div class="horizontal horizontal--center"> <button>Yes</button> <button>No</button> </div> ``` An element pinned to the middle of the screen with its text centered: ```html <div class="middle text--center"> <h1>Chapter One</h1> </div> ``` A vertical stack of options, centered both as a group and in their text: ```html <div class="vertical vertical--center text--center"> <button>New Game</button> <button>Load Game</button> <button>Settings</button> </div> ``` ## See also - [HTML Data Attributes](/v2/style-and-design/data-attributes) — The `data-` hooks that pair with these classes. --- # Responsiveness Source: https://monogatari.io/v2/style-and-design/responsiveness Section: Documentation Part of what makes Monogatari unique is how it is responsive out of the box, meaning people in all kind of devices with different form factors will be able to play your game. It is important to note that responsiveness is not the same as simply scaling your game up or down to fit the screen it's being displayed on. Responsiveness actually let's you create different stylings and layouts for different sizes so you can take advantage when there's more space or adapt your elements when it's less. Adapting to the device is done using CSS media queries. ## Default Screen-Width Breakpoints These are the width breakpoints Monogatari defines out of the box. Each one is a `min-width` media query (except the first, which is the default style), so the rules inside apply from that width upward. ```css / Default Style. Don't change. (320px) / @media screen and (max-width: 20em) {} / Extra Small Devices, Phones (480px) / @media screen and (min-width: 30em) {} / Medium Screens, Tablets (601px) / @media screen and (min-width: 37.56255em) {} / Medium Devices, Desktops (768px) / @media screen and (min-width: 48em) {} / Medium Devices, Desktops (992px) / @media screen and (min-width: 62em) {} / HD Screen, Large Devices, Wide Screens (1200px) / @media screen and (min-width: 75em) {} / Full HD Screen, Large Devices, Wide Screens (1920px) / @media screen and (min-width: 120em) {} / Retina Screen, Large Devices, Wide Screens (2560px) / @media screen and (min-width: 160em) {} / 4k Screens, Large Devices, Wide Screens (3840px) / @media screen and (min-width: 240em) {} / 5k Screens, Large Devices, Wide Screens (5120px) / @media screen and (min-width: 320em) {} ``` | Breakpoint | Approx. width | Targets | | :--- | :--- | :--- | | `max-width: 20em` | up to 320px | Default styling, applied before any breakpoint kicks in. | | `min-width: 30em` | 480px+ | Extra small devices / phones. | | `min-width: 37.56255em` | 601px+ | Medium screens / tablets. | | `min-width: 48em` | 768px+ | Medium devices / small desktops. | | `min-width: 62em` | 992px+ | Larger tablets / desktops. | | `min-width: 75em` | 1200px+ | HD screens / wide screens. | | `min-width: 120em` | 1920px+ | Full HD screens. | | `min-width: 160em` | 2560px+ | Retina / QHD wide screens. | | `min-width: 240em` | 3840px+ | 4K screens. | | `min-width: 320em` | 5120px+ | 5K screens (the largest breakpoint). | > [!NOTE] > Monogatari also pairs some of these widths with a `min-height` query (for > example `min-width: 48em` and `min-height: 27em`) to bump up font and button > sizes only when there's enough vertical space as well. --- # Style & Design Source: https://monogatari.io/v2/style-and-design Section: Documentation Guides in this section: - [Responsiveness](/v2/style-and-design/responsiveness) - [CSS Classes](/v2/style-and-design/classes) - [HTML Data Attributes](/v2/style-and-design/data-attributes) - [Icons](/v2/style-and-design/icons) - [Image Menus](/v2/style-and-design/image-menus) --- # Split Files > Splitting your Script into multiple files. Source: https://monogatari.io/v2/configuration-options/split Section: Documentation As you work on your Monogatari game, you might find that your script.js file becomes very long and cumbersome to work with. This was an involved process in 1.4.1 but luckily, in Monogatari 2.0 it is now very easy to split your script into multiple files and for Monogatari to run all of them without issue. ### Formatting Your Second Script File In Monogatari 2.0, your second script file can be formatted the same way your first script file is formatted. For example, the script section of your `script.js` file might read: ```javascript monogatari.script ({ // The game starts here. 'Start': [ "y Hello there Protaganist-senpai!", "y Wow after one line of dialog this is starting to feel pretty long.", "y Let's jump to another label in another file!", "jump theNextLabel", ] }); ``` And the script of your second script file can say: ```javascript monogatari.script ({ // The Game Continues!! 'theNextLabel': [ "y Yeah there we go! That feels so much better.", "end" ] }); ``` And this will work just fine! All you have to do after that is make sure your index.html file actually reads the file. ### Getting Monogatari to read your Split Files All we need to do in order to achieve this is to edit our index.html file's source. Find this part of the source code: ```markup  <script src="./engine/debug/debug.js"></script> <script src="./engine/core/monogatari.js"></script> <script src="./js/options.js"></script> <script src="./js/storage.js"></script> <script src="./js/script.js"></script> <script src="./js/main.js"></script> ``` And we're going to add another `<script src=""></script>`, with the source pointing to your file. For example, if you named your file `script2.js` and put it in the same folder with `script.js`, then we would change this to: ```markup  <script src="./engine/debug/debug.js"></script> <script src="./engine/core/monogatari.js"></script> <script src="./js/options.js"></script> <script src="./js/storage.js"></script> <script src="./js/script.js"></script> <script src="./js/script2.js"></script> <script src="./js/main.js"></script> ``` Just like that! Note that these files will load in order from top to bottom, so if you have any conflicting labels that are the same between them, whatever's in the later files will overwrite the ones above them. Also note that main.js should be the last file in the list. ## Internationalization with Split Files Let's say you want to make your game multi-lingual, like in the [Internationalization](/v2/configuration-options/game-configuration/internationalization) article. Split files can help to keep you organized with that too! Let's take this example from that page: ```javascript monogatari.script ({ 'English':{ 'Start':[ 'Hi, welcome to your first Visual Novel with Monogatari.' ] }, 'Español':{ 'Start':[ 'Hola, bienvenido a tu primer Novela Visual con Monogatari.' ] } }); ``` If you like, you could split this up into two files, like this: script.js: ```javascript monogatari.script ({ 'English':{ 'Start':[ 'Hi, welcome to your first Visual Novel with Monogatari.' ] } }); ``` scriptES.js: ```javascript monogatari.script ({ 'Español':{ 'Start':[ 'Hola, bienvenido a tu primer Novela Visual con Monogatari.' ] } }); ``` Then just make sure your `index.html` file points to `scriptES.js` and you're on your way! ### Another Way, for Splitting Internationalized Files After looking at the above two examples, you might want to split up files to help organize your story into chapters, and also have multiple languages at the same time! Unfortunately, if you did that by combining the above examples, you would more than likely come across a "Start Label Was Not Found" error. This would happen because although the `monogatari.script()` method adds new labels, if any label names conflict with already existing ones, it replaces them. Normally this is fine, but when working with Multi-Language games, the "English" label would be replaced in the second file, overwriting all of the work you did at run time! Luckily, there's a way around this. ```javascript monogatari.label('yourLabelName','English',[ "Let's continue the story here without issue!", ]); ``` `monogatari.label()` looks at its arguments, first the name of the label you want to write to inside the monogatari.\_script object, and then if the next argument is a string, it processes that as a language. After that, it takes an array, and from there you just write the script to your game, the same way you do the script for a label, normally! You can also use `monogatari.label()` for all of your labels. You have plenty of options! ## Related - [Internationalization](/v2/configuration-options/game-configuration/internationalization) - Multi-language setup - [Game Configuration](game-configuration/) - All game settings --- # Player Preferences > Player-adjustable preferences and their default values Source: https://monogatari.io/v2/configuration-options/player-preferences Section: Documentation Player preferences are settings that players can adjust during gameplay through the settings screen. These values are saved to storage and persist between sessions. ## Setting Default Preferences Set default preferences in your `options.js`: ```javascript monogatari.preferences({ 'Language': 'English', 'Volume': { 'Music': 1, 'Voice': 1, 'Sound': 1, 'Video': 1 }, 'TextSpeed': 20, 'AutoPlaySpeed': 5 }); ``` ## All Preferences | Preference | Type | Default | Description | | :--- | :--- | :--- | :--- | | `Language` | `string` | `'English'` | UI language / game language for multi-language games | | `Volume.Music` | `number` | `1` | Music volume (0.0 to 1.0) | | `Volume.Voice` | `number` | `1` | Voice volume (0.0 to 1.0) | | `Volume.Sound` | `number` | `1` | Sound effects volume (0.0 to 1.0) | | `Volume.Video` | `number` | `1` | Video volume (0.0 to 1.0) | | `Resolution` | `string` | `'800x600'` | Window resolution (Electron only) | | `TextSpeed` | `number` | `20` | Typewriter animation speed (lower = faster) | | `AutoPlaySpeed` | `number` | `5` | Seconds to wait before auto-advancing | ## Accessing Preferences ### Get a Preference ```javascript // Get current language const language = monogatari.preference('Language'); // Get music volume const musicVol = monogatari.preference('Volume').Music; ``` ### Set a Preference ```javascript // Set language monogatari.preference('Language', 'Español'); // Set text speed monogatari.preference('TextSpeed', 30); // Set volume monogatari.preference('Volume', { 'Music': 0.8, 'Voice': 1, 'Sound': 0.5, 'Video': 1 }); ``` ## Volume Settings Volume values range from `0.0` (muted) to `1.0` (full volume): ```javascript monogatari.preferences({ 'Volume': { 'Music': 0.7, // 70% volume 'Voice': 1.0, // 100% volume 'Sound': 0.5, // 50% volume 'Video': 0.8 // 80% volume } }); ``` ### Volume Categories | Category | Controls | | :--- | :--- | | `Music` | Background music played with `play music` | | `Voice` | Voice audio played with `play voice` | | `Sound` | Sound effects played with `play sound` | | `Video` | Video audio when playing videos | ## Text Speed The `TextSpeed` preference controls how fast the typewriter animation displays text. Lower values mean faster text: ```javascript monogatari.preferences({ 'TextSpeed': 20 // Default speed }); ``` | Value | Effect | | :--- | :--- | | `1` | Very fast (nearly instant) | | `20` | Default speed | | `50` | Slow, dramatic pacing | ## Auto-Play Speed The `AutoPlaySpeed` preference controls how long the game waits after text is fully displayed before automatically advancing: ```javascript monogatari.preferences({ 'AutoPlaySpeed': 5 // 5 seconds }); ``` | Value | Effect | | :--- | :--- | | `0` | No wait (advances immediately after text) | | `5` | Default (5 second pause) | | `10+` | Longer pause for slower readers | > [!NOTE] > `AutoPlaySpeed` is capped by the settings screen's Auto Play Speed slider. The > upper limit (`MaxAutoPlaySpeed`) is read at runtime from that slider's `max` > attribute (60 by default) — it is not a game setting you configure in > `options.js`. To raise the cap, change the slider's `max` in the settings > screen component. ## Language Preference For multi-language games, this determines which script version is used: ```javascript monogatari.preferences({ 'Language': 'Español' }); ``` See [Internationalization](/v2/configuration-options/game-configuration/internationalization) for multi-language setup. ## Resolution (Electron) For desktop builds using Electron, this sets the window resolution: ```javascript monogatari.preferences({ 'Resolution': '1280x720' }); ``` > [!NOTE] > This setting only affects Electron desktop builds. It has no effect on web-deployed games. ## Settings Screen Players can adjust these preferences through the built-in settings screen: - Audio sliders - Adjust Music, Voice, and Sound volumes - Text Speed slider - Adjust typewriter animation speed - Auto Play Speed slider - Adjust auto-advance timing - Language dropdown - Select UI/game language (if multi-language enabled) - Resolution dropdown - Select window size (Electron only) ## Programmatic Updates You can update preferences based on game events: ```javascript // In your script, use a function monogatari.script({ 'Start': [ // Player chooses "quiet mode" function() { monogatari.preference('Volume', { 'Music': 0.3, 'Sound': 0.3, 'Voice': 1, 'Video': 0.5 }); return true; }, 'The audio has been adjusted for quiet mode.', 'end' ] }); ``` ## Persistence Preferences are automatically: - Saved to storage when changed - Loaded when the game starts - Synced with the settings screen UI ## Related - [Game Configuration](game-configuration/) - Engine settings - [Internationalization](/v2/configuration-options/game-configuration/internationalization) - Multi-language setup - [Saving](/v2/configuration-options/game-configuration/saving) - Save system configuration --- # Storage Source: https://monogatari.io/v2/configuration-options/game-configuration/storage-engine Section: Documentation ## Overview Monogatari can use different storage engines so you can choose whichever works for your game best. This configuration can be found inside your `options.js` file. By default, it will look something like this: ```javascript // Define what storage engine should be used to save the game data. * // Adapters Available: // - LocalStorage: This one is used by default // - SessionStorage: Same as LocalStorage but will be cleared when the page // is closed. // - IndexedDB: The information is saved using the IndexedDB web API // - RemoteStorage: The information will be sent and retrieved from a given // URL Endpoint providing a REST API. 'Storage': { 'Adapter': 'LocalStorage', 'Store': 'GameData', 'Endpoint': '' } ``` > [!WARNING] > When releasing a game as a website, it's important to note that if people enter your game using the incognito mode in their browsers, their data will be erased when they close that window unless you choose to roll out your own server-based storage with the [Remote Storage](/v2/configuration-options/game-configuration/storage-engine#remote-storage) option. ## Local Storage This is the default storage engine used by Monogatari and it uses your browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). ## Session Storage The session storage works just like the local storage engine with the important difference that their data will be erased the moment they close the game. ## Indexed DB ## Remote Storage For remote storage, your configuration in `options.js` can be set as follow. ```javascript 'Storage': { 'Adapter': 'RemoteStorage', 'Store': '', 'Endpoint': 'https://foobar.com/gameSave' } ``` Or you may add a store name: ```javascript 'Storage': { 'Adapter': 'RemoteStorage', 'Store': 'MyGame', 'Endpoint': 'https://foobar.com/gameSave/' } ``` The storage engine concats the `Store` and `Endpoint` values as the actual RESTful API endpoint url to use: ``` https://foobar.com/gameSave/MyGame ``` ### Implementing the Remote Storage The storage mimic that of a localStorage, which is simple JSON object storage. The endpoint url should implement the below API interface: --- ```http GET [endpoint url]/ ``` > [!NOTE] > Normally, retrieves all the values in the space in a key-value JSON object. If previous storage does not exist, return an empty JSON object: `{}`. > > In keys-listing mode, return all keys stored in the space as a JSON array. Parameters | Name | Description | | ---- | ----------- | | keys | Boolean. If set to `true`, will switch to keys-listing mode. | --- ```http DELETE [endpoint url]/ ``` > [!NOTE] > Clear the entire storage object. > > Equivlant to > ```javascript > localStorage.clear(); > ``` --- ```http GET [endpoint url]/{key} ``` > [!NOTE] > Return the value of the key in the storage object. > > Equivlant to > ```javascript > localStorage.getItem(key); > ``` --- ```http POST [endpoint url]/{key} ``` > [!NOTE] > Store the value in the storage object under the key. > > The request body will be the JSON value to store. > > Equivlant to > ```javascript > localStorage.setItem(key, value); > ``` --- ```http PUT [endpoint url]/{key} ``` > [!NOTE] > Update the value in the storage object under the key. > > The request body will be the JSON value to store. The original content > should be overwritten. > > Equivlant to > ```javascript > localStorage.setItem(key, value); > ``` --- ```http DELETE [endpoint url]/{key} ``` > [!NOTE] > Return the value of the key in the storage object. > > Equivlant to > ```javascript > localStorage.removeItem(key); > ```` --- # Skip Main Menu > Skip the main menu and start directly into the game Source: https://monogatari.io/v2/configuration-options/game-configuration/skip-menu Section: Documentation You may want the game to start immediately without showing the main menu. ## Configuration To skip the main menu, change the `ShowMainScreen` setting in your `options.js`: ```javascript monogatari.settings({ 'ShowMainScreen': false }); ``` ### Default Behavior By default, `ShowMainScreen` is set to `true`, which displays the main menu: ```javascript monogatari.settings({ 'ShowMainScreen': true }); ``` ## Use Cases ### Instant Start Games For games that should begin immediately: ```javascript monogatari.settings({ 'ShowMainScreen': false, 'Label': 'Intro' // Start at a specific label }); ``` ### Demo/Preview Mode Skip the menu for demo versions: ```javascript monogatari.settings({ 'ShowMainScreen': false, 'Label': 'DemoStart' }); ``` ## Important Notes > [!NOTE] > When `ShowMainScreen` is `false`: > - The game starts at the label specified by the `Label` setting (default: `'Start'`) > - Players can still access the main menu by ending the game or through the quick menu > - Save/Load functionality remains available through the quick menu ## Splash Screen Alternative If you want something to show before the game but not the full main menu, consider using a splash screen label: ```javascript monogatari.settings({ 'ShowMainScreen': false, 'SplashScreenLabel': '_SplashScreen' }); monogatari.script({ '_SplashScreen': [ 'show scene company_logo with fadeIn', 'wait 3000', 'show scene black with fadeOut', 'jump Start' ], 'Start': [ // Your game begins here ] }); ``` ## Related - [Game Configuration](/v2/configuration-options/game-configuration) - All game settings - [Saving](/v2/configuration-options/game-configuration/saving) - Save and load configuration --- # Saving > Configure save slots and auto-save functionality Source: https://monogatari.io/v2/configuration-options/game-configuration/saving Section: Documentation Monogatari provides a flexible save system that allows players to save and load their progress. ## Save Settings | Setting | Type | Default | Description | | :--- | :--- | :--- | :--- | | `Slots` | `number` | `10` | Number of save slots available | | `SaveLabel` | `string` | `'Save'` | Prefix for save slot storage keys | | `AutoSaveLabel` | `string` | `'AutoSave'` | Prefix for auto-save slot storage keys | | `AutoSave` | `number` | `0` | Auto-save interval in minutes (0 = off) | | `Screenshots` | `boolean` | `false` | Capture the game screen on save and show it as the slot thumbnail (see [Save Slot Screenshots](#save-slot-screenshots)) | ## Number of Save Slots Control how many save slots are available: ```javascript monogatari.settings({ 'Slots': 10 // 10 save slots available }); ``` Increase for games where players may want more save points: ```javascript monogatari.settings({ 'Slots': 20 // 20 save slots }); ``` ## Save Slot Prefixes ### Multiple Games on Same Domain If you host multiple games on the same domain, they will share save data by default. To prevent this, use unique prefixes: ```javascript // Game 1 monogatari.settings({ 'Name': 'MyFirstGame', 'SaveLabel': 'Game1_Save', 'AutoSaveLabel': 'Game1_Auto' }); // Game 2 monogatari.settings({ 'Name': 'MySecondGame', 'SaveLabel': 'Game2_Save', 'AutoSaveLabel': 'Game2_Auto' }); ``` ## Auto-Save ### Enabling Auto-Save Set the `AutoSave` setting to the interval (in minutes) between automatic saves: ```javascript monogatari.settings({ 'AutoSave': 5 // Auto-save every 5 minutes }); ``` ### Disabling Auto-Save Set to `0` to disable auto-saving (default): ```javascript monogatari.settings({ 'AutoSave': 0 // Auto-save disabled }); ``` ### Auto-Save Behavior When auto-save is enabled: - The game saves automatically at the specified interval - Auto-saves are stored separately from manual saves - The load screen shows both manual saves and auto-saves - Auto-saves are labeled with the `AutoSaveLabel` prefix ## Save Slot Screenshots When the `Screenshots` setting is enabled, Monogatari captures the game screen at the moment a save is created and stores it alongside the save. The [save slot](/v2/components/save-slot) then uses that capture as its preview thumbnail instead of the scene image. ```javascript monogatari.settings({ 'Screenshots': true // Capture a screenshot for each save (default: false) }); ``` The capture is stored as a compact JPEG in a dedicated IndexedDB store and is only decoded when a slot is shown, so it doesn't bloat your regular save data. If a capture can't be taken, the slot falls back to the scene image. ### Cross-Origin Assets Require CORS The screenshot is produced by inlining every image currently on screen (backgrounds, characters, images) into the captured frame. Browsers only allow a page to read pixels from images it is permitted to access: - Same-origin assets (served from the same domain as your game) always work. - Cross-origin assets — for example when `AssetsPath.root` points at a CDN or asset host on a different domain — must be served with an `Access-Control-Allow-Origin` response header. Without it, those images can't be inlined and are captured as black, even though they display normally during play. If your screenshots come out black, confirm your asset host sends CORS headers, for example: ``` Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET ``` > [!WARNING] > A service worker that caches cross-origin responses can defeat this even when > CORS is configured: the first (no-CORS) image load gets cached as an opaque > response, which is then reused for the capture and renders black. Monogatari's > default `service-worker.js` avoids this by never caching opaque cross-origin > responses — if you customized yours, make sure it does the same. ## Storage Configuration Control how and where game data is stored: ```javascript monogatari.settings({ 'Storage': { 'Adapter': 'LocalStorage', 'Store': 'GameData', 'Endpoint': '' } }); ``` ### Storage Adapters | Adapter | Description | Use Case | | :--- | :--- | :--- | | `LocalStorage` | Browser's localStorage (default) | Most web games | | `SessionStorage` | Cleared when browser closes | Temporary/demo games | | `IndexedDB` | IndexedDB API | Large amounts of data | | `RemoteStorage` | REST API endpoint | Cloud saves | ### Remote Storage Example For cloud saves: ```javascript monogatari.settings({ 'Storage': { 'Adapter': 'RemoteStorage', 'Store': 'GameData', 'Endpoint': 'https://api.mygame.com/saves' } }); ``` ## Save Data Contents When a game is saved, Monogatari stores: - Current label and step position - All state variables - All storage variables - History for all actions - Player preferences - Timestamp and slot name ## Programmatic Save/Load ### Saving Programmatically ```javascript // Save to a specific slot monogatari.saveTo('Save_1', 'My Save Name'); // Auto-save monogatari.autoSave(); ``` ### Loading Programmatically ```javascript // Load from a slot monogatari.loadFrom('Save_1'); ``` ### Checking for Saves ```javascript // Get all save slots const saves = monogatari.saves(); // Check if a slot exists if (saves['Save_1']) { console.log('Save exists'); } ``` ## Save Slot UI The save and load screens are provided by built-in components. You can customize them using the template method: ```javascript // Customize save screen monogatari.component('save-screen').template(() => { return `  `; }); ``` ## Related - [Game Configuration](/v2/configuration-options/game-configuration) - All game settings - [Asset Preloading](/v2/configuration-options/game-configuration/asset-preloading) - Loading screen configuration - [Player Preferences](/v2/configuration-options/player-preferences) - Player settings --- # Internationalization > Making Monogatari games multilingual. Source: https://monogatari.io/v2/configuration-options/game-configuration/internationalization Section: Documentation ## Overview You can create a multi-language game pretty easily. To do so you need to follow these simple steps: ### 1. Enable the `MultiLanguage` setting Go to the `options.js` file and change the `'MultiLanguage'` value to `true`. ```javascript // Change to true for a MultiLanguage GameScreen. 'MultiLanguage': true, ``` This will let monogatari know that you're planning to have your script in multiple languages. If you reload the page however, you'll most likely get an error like this one: ![](https://cdn.restlessdreams.cloud/1d8777bc-c68a-419b-9e44-6dbdedf03764.webp) This is normal and is caused because while we have indicated we would be having multiple versions of our script in multiple languages, we haven't changed the structure of our script to match that. ### 2. Change your Script Format Next we will be changing the script to support Multi Language games. A single language script as you know is defined as an object with a list of labels and usually looks something like this: ```javascript monogatari.script ({ 'Start': [ 'Hi, welcome to your first Visual Novel with Monogatari.', 'jump other' ], 'other': [ 'Another Label!', 'end' ] }); ``` Note how each label is in the top level of the script objects hierarchy. A _Multi Language_ script will instead have language objects in the top level and inside of them, the labels of the script that correspond to that language, for example: ```javascript monogatari.script ({ 'English':{ 'Start': [ 'Hi, welcome to your first Visual Novel with Monogatari.', 'jump other' ], 'other': [ 'Another Label!', 'end' ] }, 'Español':{ 'Start': [ 'Hola, bienvenido a tu primer Novela Visual con Monogatari.', 'jump other' ], 'other': [ 'Otro label!', 'end' ] } }); ``` Note how we essentially duplicated our script inside this new language objects and translated it for each language. > [!WARNING] > When saving a game, monogatari saves the `label` and `step` (index of the statement) it's currently on. For saved games to be fully compatible with each other, your different scripts should have the same label names and number of statements in them, otherwise, a game saved in one language would be invalid if the player changed language again and tried to load it. If you do a [jump](/v2/script-actions/jump) to a label that exists in one translation, but does not exist in the language that the player has selected for example, they will get an error telling them that the label does not exist, so be careful when crafting your script! > > In case some differences can't be avoided, you can rely on the `next` action to act as a filler and make all scripts have the same size. If you have your script split in multiple files, you can read more on how to configure internationalization with split files here: ### 3. The Language Selection Screen ![](https://cdn.restlessdreams.cloud/479e9e3f-3928-4320-aaf0-dd6ebb38ce64.webp) Once you've formatted your script correctly, a language selection screen will appear for players that haven't selected a language yet. It will automatically detect the languages in your script and show buttons like the ones shown in the image. > [!NOTE] > You most likely won't see this screen appear to you because you transitioned from a single language game to a _multi language_ one and thus, your settings were already set. > > If you want to trigger this screen, you'll have to remove the settings from your storage using the dev tools. Players are also able to change their language from the settings screen. The following image shows the language selection setting that appears automatically when a _multi language_ game is configured: ![](https://cdn.restlessdreams.cloud/e4e20f99-8a5c-4841-8d58-6b7e11ee6edf.webp) In case you don't want the language selection screen to appear or have built your own, it can be disabled from the options.js file by changing the `LanguageSelectionScreen` property to `false`: ```javascript // If the 'Multilanguage' setting is set to `true`. This will enable a // language selection screen that will be shown before the asset loading // screen. If set to false, the loading screen will appear first instead and // players will have to change the language from the settings screen. 'LanguageSelectionScreen': false, ``` ### 4. Set the Default Language Preference Finally, you need to provide a default language for your game. While players will be able to choose their language, monogatari does need something to fall back to. Go to the `options.js` file once more and this time, go to the preferences section in the bottom. There, you should change the `'Language'` property to the name of the language you want to have by default. ```javascript // Initial Language for Multilanguage Games or for the Default GUI Language. 'Language': 'Français', ``` ## Supported Languages Monogatari already has built-in support for the following languages: * `Bahasa Indonesia` * `Беларуская` * `Deutsch` * `English` * `Español` * `Français` * `Nederlands` * `Português` * `Русский` * `اللغه العربية` * `한국어` * `日本語` * `简体中文` * `toki pona` That means UI translations for those languages are available and the full UI will be shown in the correct language. You can also retrieve the list of available translations programmatically using the `monogatari.translations ()` function. This function will return an object with all the available languages and the UI string translations for them. ![](https://cdn.restlessdreams.cloud/3fbc352c-ff52-4ca3-9c1b-939155295afa.webp) ## Translating the Engine UI for a not-yet-supported language If you need to translate the game into a language that Monogatari doesn't include in the [supported languages](/v2/configuration-options/game-configuration/internationalization#supported-languages) or simply want to modify an existing translation, you can define your own UI translations as follows: ```javascript monogatari.translation ('YourLanguage', { 'SomeString': 'Your Translation' }); ``` You can also contribute to monogatari by adding new language translations to it or updating existing ones. You can learn more in the [Translations documentation](/v2/advanced-monogatari-development/translations). ### Adding the UI translations To make a new language available for your players to choose from, you'll have to add translations for all the strings the UI requires. You can take the [English strings file](https://github.com/Monogatari/Monogatari/blob/develop/src/translations/English.js) as reference so you can gather all the required strings and add your own translations for your language. You can also get a complete list of every string to translate programmatically by using the `monogatari.translation ('<language_key>')` function, for example: ![](https://cdn.restlessdreams.cloud/17237e71-89cc-43ee-84a3-3bea1841d938.webp) ### Adding the language metadata Each language also requires some metadata that will be used by monogatari. | Metadata | Description | | :--- | :--- | | `code` | The 2 letter code that represents that language. This code must be a valid [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) since it will be used to format the dates shown on the save slots. | | `icon` | An emoji that will be shown as the icon for the language in the language selection screen. | Here's an example of the definition of a language metadata: ```javascript monogatari.languageMetadata ('Español', { code: 'es', icon: '🇲🇽' }); ``` Once you've setup all the string translations and language metadata, all you need is adding your script for your new language and the option will appear automatically both on the language selection and the settings screens. --- # Asset Preloading > Configure asset preloading and caching for web deployment Source: https://monogatari.io/v2/configuration-options/game-configuration/asset-preloading Section: Documentation When releasing your game online, asset loading is one of the most important issues to solve. Monogatari's built-in preloading ensures players can enjoy your game even on slow connections. ## Settings Overview | Setting | Type | Default | Description | | :--- | :--- | :--- | :--- | | `Preload` | `boolean` | `true` | Enable/disable asset preloading | | `ServiceWorkers` | `boolean` | `true` | Enable service worker caching | ## Built-In Preloading The preloading screen shows a progress bar while assets are loaded before the game starts. ### Enable Preloading (Default) ```javascript monogatari.settings({ 'Preload': true }); ``` With preloading enabled: - A loading screen appears when entering the game - Assets are loaded before gameplay begins - Players experience smooth gameplay without loading delays ### The `default` Preload Block For optimal performance, define a `default` preload block to specify exactly which assets should be preloaded at startup: ```javascript monogatari.action('Preload').blocks({ 'default': { music: ['main_theme', 'menu_music'], scenes: ['title_screen', 'intro'], sounds: ['click', 'confirm'], characters: { 'y': ['normal', 'happy'] } } }); ``` With a `default` block: - Only specified assets are preloaded (faster initial load) - Audio is decoded to AudioBuffers (instant playback) - Images are pre-decoded (no rendering delay) Without a `default` block (legacy behavior): - ALL registered assets are preloaded to browser cache - Assets are fetched but not decoded until first use - May have slight delay on first playback See the [Preload action documentation](/v2/script-actions/preload#the-default-block) for details. ### Disable Preloading ```javascript monogatari.settings({ 'Preload': false }); ``` > [!WARNING] > Disabling preloading means assets load on-demand during gameplay. This may cause: > - Stuttering when new assets are needed > - Poor experience on slow connections > - Delayed audio/visual appearance ### When Preloading is Skipped Preloading is automatically skipped in: - Electron apps - Assets are bundled locally - Cordova apps - Assets are packaged with the app - file:// protocol - Opening HTML directly without a server ## Service Workers Cache Service Workers provide powerful caching for web-deployed games. ### How It Works 1. On first visit, assets are cached as they're loaded 2. On subsequent visits, cached assets load instantly 3. Updated assets are fetched in the background 4. Games can work offline once cached This uses a "cache-then-update" strategy - players see cached content immediately while updates download silently. ### Enable Service Workers (Default) ```javascript monogatari.settings({ 'ServiceWorkers': true }); ``` ### Disable Service Workers ```javascript monogatari.settings({ 'ServiceWorkers': false }); ``` ### Service Worker Configuration Configure your `service-worker.js` file: ```javascript // The name of your game (no spaces or special characters) const name = 'MyVisualNovel'; // Cache version - change to force re-caching all assets const version = '0.1.0'; ``` #### When to Change Version - Major updates with many changed assets - Critical bug fixes in assets - Usually not needed - the cache strategy updates automatically > [!NOTE] > You don't need to change the version when adding or removing files. The cache strategy handles this automatically. ### Service Worker Requirements Service Workers require: - HTTP or HTTPS protocol (not `file://`) - A web server (local or remote) #### Local Development If you open files directly (`file://` protocol), you'll see: ``` Service Workers are available only when serving your files through a server. ``` This is normal! Use a local server for development: ```bash # Python python -m http.server 8000 # Node.js npx serve # PHP php -S localhost:8000 ``` Once deployed to a web server, the warning disappears. ## Progressive Web App (PWA) Service Workers are part of making your game a [Progressive Web App](https://en.wikipedia.org/wiki/Progressive_web_app), which provides: - Offline play - Play without internet after first load - Install to device - Add to home screen like a native app - Fast loading - Cached assets load instantly - Reduced bandwidth - Only downloads changed assets See the [Web Deployment](/v2/releasing-your-game/web) documentation for full PWA setup. ## Preload Action For fine-grained control over what and when to preload, use the [Preload action](/v2/script-actions/preload): ```javascript monogatari.script({ 'Start': [ // Preload assets for the next scene 'preload scene forest', 'preload music theme', 'show scene bedroom', 'y Let me tell you about the forest...', // Forest assets are now ready 'show scene forest', 'end' ] }); ``` ## Best Practices ### For Small Games (< 50MB) ```javascript monogatari.settings({ 'Preload': true, 'ServiceWorkers': true }); ``` Let everything preload upfront for the smoothest experience. ### For Large Games (> 50MB) ```javascript monogatari.settings({ 'Preload': true, 'ServiceWorkers': true }); // Define a minimal default block for essential assets monogatari.action('Preload').blocks({ 'default': { music: ['main_theme'], scenes: ['title_screen'] }, // Load chapter-specific assets on-demand 'chapter1': { scenes: ['school_gate', 'classroom'], music: ['chapter1_theme'], characters: { 'y': ['happy', 'sad', 'normal'] } }, 'chapter2': { scenes: ['rooftop', 'library'], music: ['chapter2_theme'] } }); ``` Then in your script: ```javascript monogatari.script({ 'Start': [ 'show scene title_screen', 'Welcome to my game!', 'jump Chapter1' ], 'Chapter1': [ 'preload block chapter1 blocking', // Load chapter assets 'show scene school_gate', // ... chapter content ] }); ``` See the [Preload action documentation](/v2/script-actions/preload) for advanced preloading strategies. ## Related - [Game Configuration](/v2/configuration-options/game-configuration) - All game settings - [Preload Action](/v2/script-actions/preload) - Runtime preloading - [Web Deployment](/v2/releasing-your-game/web) - Releasing your game online --- # Game Configuration Source: https://monogatari.io/v2/configuration-options/game-configuration Section: Documentation Game settings control how your visual novel behaves. These settings are typically defined in your `options.js` file using `monogatari.settings()`. ## Setting Values ```javascript // Set multiple settings at once monogatari.settings({ 'Name': 'My Awesome VN', 'Version': '1.0.0', 'AutoSave': 5 }); // Get a specific setting const gameName = monogatari.setting('Name'); // Set a single setting monogatari.setting('AutoSave', 10); ``` ## All Settings | Setting | Type | Default | Description | | :--- | :--- | :--- | :--- | | `Name` | `string` | `'My Visual Novel'` | Game name used for storage. Don't change after release. | | `Version` | `string` | `'0.1.0'` | Game version in [semantic versioning](https://semver.org/). | | `Label` | `string` | `'Start'` | Initial label where the game begins. | | `Slots` | `number` | `10` | Number of save slots available. | | `MultiLanguage` | `boolean` | `false` | Enable multi-language support. | | `LanguageSelectionScreen` | `boolean` | `true` | Show language selection before loading. | | `MainScreenMusic` | `string` | `''` | Music asset ID to play on main menu. | | `SaveLabel` | `string` | `'Save'` | Prefix for save slot storage keys. | | `AutoSaveLabel` | `string` | `'AutoSave'` | Prefix for auto-save slot storage keys. | | `ShowMainScreen` | `boolean` | `true` | Show main menu on game start. | | `Preload` | `boolean` | `true` | Enable asset preloading on web. | | `AutoSave` | `number` | `0` | Auto-save interval in minutes (0 = off). | | `Screenshots` | `boolean` | `false` | Capture a screenshot when saving, used as the [save slot](/v2/components/save-slot)'s preview background. Cross-origin assets must send CORS headers or they capture as black — see [Saving](/v2/configuration-options/game-configuration/saving#cross-origin-assets-require-cors). | | `ServiceWorkers` | `boolean` | `true` | Enable service workers for caching. | | `AspectRatio` | `string` | `'16:9'` | Aspect ratio for backgrounds. | | `ForceAspectRatio` | `string` | `'None'` | Force aspect ratio: `'None'`, `'Visuals'`, or `'Global'`. | | `TypeAnimation` | `boolean` | `true` | Enable typewriter text animation. | | `NVLTypeAnimation` | `boolean` | `true` | Enable typewriter animation in NVL mode. | | `NarratorTypeAnimation` | `boolean` | `true` | Enable typewriter animation for narrator. | | `CenteredTypeAnimation` | `boolean` | `true` | Enable typewriter animation for centered text. | | `InstantText` | `boolean` | `false` | Reveal each line of dialog instantly instead of animating it letter by letter. | | `Orientation` | `string` | `'any'` | Mobile orientation: `'any'`, `'portrait'`, or `'landscape'`. | | `Skip` | `number` | `0` | Skip speed in ms (0 = disabled). | | `SplashScreenLabel` | `string` | `'_SplashScreen'` | Label for splash screen (if exists). | | `AllowRollback` | `boolean` | `true` | Allow players to go back in the game. | | `ExperimentalFeatures` | `boolean` | `false` | Enable experimental/unstable features. | ## Text animation settings The typewriter (letter-by-letter) animation is controlled by a few related settings that work together. The most important one is `TypeAnimation`, which acts as the global switch — when it's `false`, the type-writer never animates and the per-context settings below have no effect. | Setting | Default | What it controls | | :--- | :--- | :--- | | `TypeAnimation` | `true` | Global on/off switch for the typing animation. When `false`, all dialog appears instantly regardless of the settings below. | | `NarratorTypeAnimation` | `true` | Whether the narrator's lines animate. | | `CenteredTypeAnimation` | `true` | Whether the special centered character's lines animate. | | `NVLTypeAnimation` | `true` | Whether dialog shown in NVL mode animates. | The per-context settings are only consulted when `TypeAnimation` is enabled — they let you turn the animation off for a specific context (the narrator, the centered character, or NVL dialog) while keeping it on everywhere else. Turning a per-context setting on while `TypeAnimation` is `false` does nothing. ```javascript monogatari.settings ({ 'TypeAnimation': true, // Animate dialog in general... 'NarratorTypeAnimation': false // ...but show the narrator's lines instantly. }); ``` `InstantText` is separate from the animation switches. It changes what happens when a player finishes a still-animating line (for example, by clicking while the text is typing): | Setting | Default | What it controls | | :--- | :--- | :--- | | `InstantText` | `false` | When `true`, finishing an in-progress line shows all remaining text instantly and drops non-node formatting. When `false`, finishing instead fast-forwards the animation at the fastest speed while keeping formatting. | ## Assets Path The `AssetsPath` setting controls where assets are loaded from: ```javascript monogatari.settings({ 'AssetsPath': { 'root': 'assets', 'characters': 'characters', 'icons': 'icons', 'images': 'images', 'music': 'music', 'scenes': 'scenes', 'sounds': 'sounds', 'ui': 'ui', 'videos': 'videos', 'voices': 'voices', 'gallery': 'gallery' } }); ``` ## Storage Configuration Control how game data is stored: ```javascript monogatari.settings({ 'Storage': { 'Adapter': 'LocalStorage', // LocalStorage, SessionStorage, IndexedDB, or RemoteStorage 'Store': 'GameData', // Storage key/database name 'Endpoint': '' // URL for RemoteStorage adapter } }); ``` ### Storage Adapters | Adapter | Description | | :--- | :--- | | `LocalStorage` | Default. Persists in browser storage. | | `SessionStorage` | Cleared when page is closed. | | `IndexedDB` | Uses IndexedDB web API. | | `RemoteStorage` | Sends data to a REST API endpoint. | ## Detailed Documentation - [Asset Preloading](/v2/configuration-options/game-configuration/asset-preloading) - Preloading and caching settings - [Internationalization](/v2/configuration-options/game-configuration/internationalization) - Multi-language game setup - [Saving](/v2/configuration-options/game-configuration/saving) - Save slots and auto-save configuration - [Skip Main Menu](/v2/configuration-options/game-configuration/skip-menu) - Starting directly into the game ## Related - [Player Preferences](/v2/configuration-options/player-preferences) - Player-adjustable settings - [Split Files](/v2/configuration-options/split) - Organizing scripts across multiple files --- # Configuration Options Source: https://monogatari.io/v2/configuration-options Section: Documentation Guides in this section: - [Player Preferences](/v2/configuration-options/player-preferences) - [Split Files](/v2/configuration-options/split) --- # Text-Box Source: https://monogatari.io/v2/components/text-box Section: Documentation ## Description ```markup <text-box></text-box> ``` The text-box component is responsible for displaying character dialogs, narrator text, and NVL (Novel) mode content. It contains the character name, side image (expression), and the dialog text itself. Source Code: [https://github.com/Monogatari/Monogatari/tree/develop/src/components/text-box](https://github.com/Monogatari/Monogatari/tree/develop/src/components/text-box) ## Structure The text-box component renders the following structure: ```html <text-box data-component="text-box"> <div data-content="name"> <span data-ui="who" data-content="character-name"></span> </div> <div data-content="side-image"> <img data-ui="face" alt="" data-content="character-expression"> </div> <div data-content="text"> <type-writer data-ui="say" data-content="dialog"></type-writer> </div> </text-box> ``` In NVL mode, the `<type-writer>` element is not included in the initial render, as dialogs are appended dynamically. ## Properties | Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | `mode` | `'adv'` \| `'nvl'` | `'adv'` | The display mode. `adv` is the standard Adventure mode (single dialog at a time). `nvl` is Novel mode (multiple dialogs on screen). | ## State | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `hidden` | `boolean` | `false` | Whether the text box is hidden. When set to `true` the element is hidden; when set back to `false` it is shown again (as a CSS grid). While `hidden` is `true`, calling `show()` is a no-op, so the box stays hidden until it is explicitly unhidden. | The `hidden` state is toggled by the [Show Text Box](/v2/script-actions/show-textbox) and [Hide Text Box](/v2/script-actions/hide-textbox) script actions, which set it to `false` and `true` respectively (and persist the choice in the game state so it survives saving/loading). > [!NOTE] > The quick-menu Hide button is a separate, distraction-free mechanism. It hides the text-box element directly (toggling the `distraction_free` global), and does not change this `hidden` state. > [!TIP] > The typewriter animation used inside the text box is controlled by the `TypeAnimation` family of settings. See [Game Configuration](/v2/configuration-options/game-configuration) for details. ## Data Attributes | Attribute | Description | | :--- | :--- | | `data-speaking` | Set to the character ID currently speaking. Updated by the Dialog action. | | `data-expression` | Set to the current expression name when a side image is displayed. | ## Methods ### `show(): void` Shows the text-box element using CSS grid display. If the `hidden` state is currently `true`, this method returns early and does nothing, so a box hidden via the [Hide Text Box](/v2/script-actions/hide-textbox) action stays hidden. ```javascript const textBox = document.querySelector('text-box'); textBox.show(); ``` ### `checkUnread(): void` Checks if there is content in the text box that the player hasn't scrolled to see. If there is unread content (overflow), adds the `unread` CSS class to the text-box. This is automatically called by the [Dialog action](/v2/script-actions/dialogs) after writing NVL dialogs. ```javascript const textBox = document.querySelector('text-box'); textBox.checkUnread(); ``` ### `setProps(props: object): void` Update component properties. Used to switch between modes: ```javascript const textBox = document.querySelector('text-box'); textBox.setProps({ mode: 'nvl' }); ``` ### `content(name: string): DOM` Access named content areas within the component: ```javascript const textBox = document.querySelector('text-box'); const dialogArea = textBox.content('dialog'); const nameArea = textBox.content('name'); ``` ## CSS Classes | Class | Description | | :--- | :--- | | `unread` | Applied when there is scrollable content the player hasn't seen. Typically used to show a scroll indicator. | | Custom classes | The [Dialog action](/v2/script-actions/dialogs) can apply custom classes via the dialog syntax (e.g., `'y:happy:highlight Dialog text'`). | ## Content Areas | Name | Selector | Description | | :--- | :--- | :--- | | `name` | `[data-content="name"]` | Container for the character name | | `character-name` | `[data-content="character-name"]` | The character name span element | | `side-image` | `[data-content="side-image"]` | Container for the expression/side image | | `character-expression` | `[data-content="character-expression"]` | The expression image element | | `text` | `[data-content="text"]` | Container for the dialog text | | `dialog` | `[data-content="dialog"]` | The type-writer element containing dialog | ## Display Modes ### ADV Mode (Adventure) The default mode. Displays one dialog at a time with character name, optional side image, and text. When a new dialog is shown, the previous one is replaced. ### NVL Mode (Novel) Displays multiple dialogs on screen simultaneously, scrolling as new dialogs are added. Each dialog entry includes the speaker's name (if not narrator) and the dialog text. In NVL mode: - Side images are not displayed - Dialogs are appended rather than replaced - The text area is scrollable - The `unread` class indicates when new content is below the visible area ## Styling The text-box component can be styled using CSS. Key selectors: ```css /* Main text-box container / text-box { / Your styles / } / ADV mode specific / text-box[data-speaking] { / Styles when a character is speaking / } / NVL mode specific / text-box[mode="nvl"] { / NVL mode styles / } / Character name / text-box [data-ui="who"] { / Character name styles / } / Side image / text-box [data-ui="face"] { / Expression/side image styles / } / Dialog text area / text-box [data-content="text"] { / Text container styles / } / Unread indicator / text-box.unread { / Show scroll indicator / } text-box.unread::after { content: '▼'; / Position indicator / } ``` ## Related - [Dialog Action](/v2/script-actions/dialogs) - The action that controls text-box content - [Type Writer](#type-writer) - The component that handles text animation - [Centered Dialog](#centered-dialog) - Alternative display for centered text --- # Save Slot Source: https://monogatari.io/v2/components/save-slot Section: Documentation ## Component Structure The following code is this component's initial HTML structure. Remember you can change this structure any time by using the [`template()` component built-in function](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure). ```javascript let background = ''; if (this.props.screenshot) { // With the `Screenshots` setting enabled, each save stores a screenshot // taken at the moment it was created and it's used as the slot background. background = `url(${this.props.screenshot})`; } else { const assetsPath = this.engine.setting ('AssetsPath'); const hasImage = this.props.image && this.engine.asset ('scenes', this.props.image); if (hasImage) { background = `url(${assetsPath.root}/${assetsPath.scenes}/${this.engine.asset ('scenes', this.props.image)})`; } else if (this.data && 'game' in this.data && this.data.game) { if (this.data.game.state.background) { background = this.data.game.state.background; if (background.indexOf (' with ') > -1) { background = Text.prefix (' with ', background); } background = Text.suffix ('show background', background); } else if (this.data.game.state.scene) { background = this.data.game.state.scene; if (background.indexOf (' with ') > -1) { background = Text.prefix (' with ', background); } background = Text.suffix ('show scene', background); } } } const useBackgroundImage = !!this.props.screenshot || (this.props.image && this.engine.asset ('scenes', this.props.image)); return ` <button data-delete='${this.props.slot}' aria-label="${this.engine.string ('Delete')} Slot ${this.props.name}"><span class='fas fa-times'></span></button> <small class='badge'>${this.props.name}</small> <div data-content="background" style="${useBackgroundImage ? 'background-image' : 'background'}: ${background}"></div> <figcaption>${DateTime.fromISO (this.props.date).toLocaleString (DateTime.DATETIME_MED_WITH_SECONDS)}</figcaption> `; ``` > [!NOTE] > Save dates are formatted with [Luxon](https://moment.github.io/luxon/)'s `DateTime` > (`DateTime.fromISO (...).toLocaleString (...)`), not Moment.js. Older > customizations that call `moment (...)` must be updated to use Luxon. ## Slot Backgrounds Each slot previews where the player was when they saved, in this order of preference: 1. If the [`Screenshots`](/v2/configuration-options/game-configuration/saving) setting is enabled, the slot uses the screenshot captured at save time (`this.props.screenshot`). 2. Otherwise, if the current scene has an associated image, that scene image is used. 3. Otherwise, the slot falls back to the saved `background` / `scene` state. > [!NOTE] > The save-time screenshot inlines every on-screen image, so background and > character assets served from another origin must send CORS headers or they > are captured as black. See [Cross-Origin Assets Require CORS](/v2/configuration-options/game-configuration/saving#cross-origin-assets-require-cors). ## Customizing ### Restyle the slot A save slot renders four pieces: a delete `<button>` (with a `data-delete` attribute), the slot name in a `<small class='badge'>`, the preview in `<div data-content="background">`, and the date in a `<figcaption>`. The most common tweak is restyling those parts with CSS: ```css / The slot preview image / background / save-slot [data-content="background"] { border-radius: 0.5rem; } / The name badge / save-slot .badge { / Your styles / } / The delete button / save-slot button[data-delete] { / Your styles / } / The save date caption / save-slot figcaption { / Your styles / } ``` ### Change the structure To change the markup itself (for example to show extra information on each slot), override it with the [`template()`](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure) function. The structure shown above is what the default template produces; keep the `data-delete` button and the `data-content="background"` element so deletion and the slot preview keep working. --- # Choice Container Source: https://monogatari.io/v2/components/choice-container Section: Documentation ## Props | Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | `choices` | `ChoiceItem[]` | `[]` | The list of choice buttons to render, one button per item. | | `classes` | `string` | `''` | Space-separated list of extra CSS classes added to the container element itself when it mounts. | ### Choice Item Each entry in `choices` describes a single button: | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `Text` | `string` | Yes | The button label. Variables in it are replaced before rendering. | | `Do` | `string` | Yes | The script statement to run when the button is clicked (rendered as `data-do`). | | `Class` | `string` | No | Extra CSS class applied to that individual button. | | `Clickable` | `() => boolean \| Promise<boolean>` | No | Optional guard. If it (a)synchronously resolves falsy, the button is rendered `disabled`. | | `_key` | `string` | — | Internal identifier for the choice, set by the engine (rendered as `data-choice`). | ## Component Structure The following code is this component's initial HTML structure. Remember you can change this structure any time by using the [`template()` component built-in function](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure). ```javascript const choices = this.props.choices.map ((choice) => { if (typeof choice.Clickable === 'function') { return new Promise ((resolve, reject) => { this.engine.assertAsync (choice.Clickable, this.engine).then (() => { resolve (`<button data-do="${choice.Do}" ${ choice.Class ? `class="${choice.Class}"`: ''} data-choice="${choice._key}">${choice.Text}</button>`); }).catch (() => { resolve (`<button data-do="${choice.Do}" ${ choice.Class ? `class="${choice.Class}"`: ''} data-choice="${choice._key}" disabled>${choice.Text}</button>`); }); }); } return Promise.resolve (`<button data-do="${choice.Do}" ${ choice.Class ? `class="${choice.Class}"`: ''} data-choice="${choice._key}">${choice.Text}</button>`); }); return Promise.all (choices).then ((choices) => ` <div data-content="wrapper"> ${ choices.join('') } </div> `); ``` --- # Main Screen > The screen that hosts the main menu and plays the menu's ambient music. Source: https://monogatari.io/v2/components/main-screen Section: Documentation ## Description ```markup <main-screen></main-screen> ``` The main-screen is what players see when the game first loads — it hosts the [Main Menu](/v2/components/main-menu) and acts as the backdrop behind it. It's a [screen component](/v2/building-blocks/components), so like every other screen it has an `open` state and is shown or hidden as the player moves in and out of the menu. ## Structure The main-screen renders the main menu inside it: ```markup <main-screen data-component="main-screen"> <main-menu></main-menu> </main-screen> ``` You'll rarely change the main-screen itself — to change the buttons it shows, customize the [Main Menu](/v2/components/main-menu); to change the look, style `main-screen` and its children with CSS (a full-screen background image is the most common change). ## Main menu music The main-screen owns the menu's ambient music. When it opens it plays the track set in the [`MainScreenMusic`](/v2/configuration-options/game-configuration) setting, and it stops that track once the player starts the game. ```javascript monogatari.settings ({ 'MainScreenMusic': 'theme' }); ``` > [!NOTE] > `MainScreenMusic` is the id of a music asset, not a file name. Declare the track > first — `monogatari.assets ('music', { 'theme': 'theme.ogg' })` — then reference it > here by its id. ## Related - [Main Menu](/v2/components/main-menu) — The buttons rendered inside this screen. - [Game Configuration](/v2/configuration-options/game-configuration) — The `MainScreenMusic` setting. - [Play Music](/v2/script-actions/play-music) — How music assets are declared and played. --- # Loading Screen > The screen showing the asset preloading progress Source: https://monogatari.io/v2/components/loading-screen Section: Documentation ## Description ```markup <loading-screen></loading-screen> ``` This is the first screen that will be shown if Asset Preloading is enabled on the game's configuration. Component tag: loading-screen ## Component Structure The following code is this component's initial HTML structure. Remember you can change this structure any time by using the [`template()` component built-in function](/v2/building-blocks/components/built-in-functions#get-or-modify-the-html-structure). ```markup <loading-screen data-component="loading-screen" data-screen="loading"> <div data-content="wrapper"> <h2 data-string="Loading" data-content="title">Loading</h2> <progress value="0" max="100" data-content="progress"></progress> <small data-string="LoadingMessage" data-content="message">Wait while the assets are loaded.</small> </div> </loading-screen> ``` ## State | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `progress` | `number` | `0` | How many assets have finished loading so far. Each `assetLoaded` event increments it, and the new value is written to the `<progress>` element's `value`. | > [!NOTE] > Being a screen component, the loading-screen also inherits the base `open` state, which is set to `true` when preloading starts and back to `false` when it finishes. ## Props | Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | `max` | `number` | `0` | The total number of assets queued for preloading. Each `assetQueued` event increments it, and the new value becomes the `<progress>` element's `max`. | ## Preload Events The loading screen is driven entirely by the preload events the engine emits while it loads the assets declared in your game's [Asset Preloading](/v2/configuration-options/game-configuration/asset-preloading) configuration: | Event | Effect on the loading screen | | :--- | :--- | | `willPreloadAssets` | Opens the screen (`open` → `true`). | | `assetQueued` | Increments `max` (one more asset to load). | | `assetLoaded` | Increments `progress` (one more asset finished). | | `didPreloadAssets` | Closes the screen (`open` → `false`). | For the full list of engine events and how to listen for them yourself, see [Events](/v2/advanced-monogatari-development/events). --- # Quick Menu > The in-game toolbar with save, load, settings, skip and other shortcuts — and how to add your own buttons. Source: https://monogatari.io/v2/components/quick-menu Section: Documentation ## Description ```markup <quick-menu></quick-menu> ``` The quick menu is the small toolbar at the bottom of the screen (top on mobile) that gives players quick access to common actions while playing. It renders one button per entry in its configuration, so you can add, remove and reorder buttons freely. ## Default buttons Out of the box the quick menu shows: | Button | What it does | Notes | | :--- | :--- | :--- | | Back | Roll back to the previous statement | Removed if [`AllowRollback`](/v2/configuration-options/game-configuration) is `false`. | | Hide | Hide the text box to admire the scene | | | Log | Open the [dialog log](/v2/components/dialog-log) | Added by the dialog-log component. | | Auto | Toggle auto-play | | | Skip | Enter skip mode | Removed if the [`Skip`](/v2/configuration-options/game-configuration) speed is `0`. | | Save | Open the [Save screen](/v2/components/save-screen) | | | Load | Open the [Load screen](/v2/components/load-screen) | | | Settings | Open the [Settings screen](/v2/components/settings-screen) | | | Quit | Quit to the main menu | | > [!NOTE] > Two buttons are conditional: Skip only appears when the `Skip` setting is greater > than `0`, and Back only appears when `AllowRollback` is `true`. ## A button definition Each button is an object with these properties: | Key | Description | | :--- | :--- | | `string` | The translation key for the button's label (see [Translations](/v2/advanced-monogatari-development/translations)). | | `icon` | A [Font Awesome](/v2/style-and-design/icons) icon class, e.g. `'fas fa-tasks'`. | | `data` | An object of `data-` attributes. `data.action` is usually the [action](/v2/style-and-design/data-attributes) the button triggers. | | `element` | Optional. The tag to render (defaults to `button`). | ## Methods The quick menu shares its button API with the [Main Menu](/v2/components/main-menu) (both are menu components). ### Add Button ```javascript static addButton ({ string, icon, data, ... }): void ``` Adds a button to the end of the menu. ```javascript monogatari.component ('quick-menu').addButton ({ string: 'Stats', icon: 'fas fa-tasks', data: { action: 'show-stats' } }); ``` ### Add Button After ```javascript static addButtonAfter (after: string, { string, icon, data, ... }): void ``` Adds a button immediately after the one whose `string` matches `after`: ```javascript monogatari.component ('quick-menu').addButtonAfter ('Back', { string: 'Stats', icon: 'fas fa-tasks', data: { action: 'show-stats' } }); ``` ### Add Button Before ```javascript static addButtonBefore (before: string, { string, icon, data, ... }): void ``` Adds a button immediately before the one whose `string` matches `before`: ```javascript monogatari.component ('quick-menu').addButtonBefore ('Back', { string: 'Stats', icon: 'fas fa-tasks', data: { action: 'show-stats' } }); ``` ### Remove Button ```javascript static removeButton (string: string): void ``` Removes a button by its `string`. For example, to hide the Settings button: ```javascript monogatari.component ('quick-menu').removeButton ('Settings'); ``` > [!TIP] > Your button's `data.action` needs something to respond to it. Pair a custom button > with a [Component](/v2/building-blocks/components) or an event listener that > reacts to that action — see [HTML Data Attributes](/v2/style-and-design/data-attributes). ## Related - [Main Menu](/v2/components/main-menu) — Shares the same button API. - [Dialog Log](/v2/components/dialog-log) — Adds the Log button to the quick menu. - [Help Screen](/v2/components/help-screen) — Documents these buttons and their keyboard shortcuts for players. --- # Credits Screen > The credits page so players can see who made the game Source: https://monogatari.io/v2/components/credits Section: Documentation ## Description ```markup <credits-screen></credits-screen> ``` Attribution is important. People like knowing who made the games they love, and collaborators deserve credit for their work. ```javascript monogatari.configuration ('credits', { "Developers": { "Artist": "Yui", "Scenario Writer": "Gale", }, "Donors": { "Top Level Donors": [ "Tommy", "Scotty", "Lanny", "Robby", "Josie", "Freddy", "Bobby", "Lindsey" ], "Patrons": [ "Alex", "Shine", "Mika" ], }, "Special Thanks to": { "My parents": ["Mom", "Dad"], "My siblings": ["Brother", "Sister"], } }); ``` This will create a credits page that looks like this! ![A credits page listing all of the people written in the example code above.](https://cdn.restlessdreams.cloud/50c19dac-a8e5-4c8c-99e3-9784c9774739.webp) As you can see, Credits are stored as an object, just like most things in Monogatari. Also, like most things in Monogatari, the Credits page supports HTML, so if you want to make each of those names a clickable link that leads to the person's website, or email address, or something like that, you can easily achieve all of these things by inserting hyperlinks, like: ```javascript monogatari.configuration ('credits', { Developers: { Coder: "<a href="https://monogatari.io">Hyuchia</a>", } }); ``` If the credits object in your script.js file is empty, the credits button will not appear. No need to worry the User with an empty credits page, but as soon as you fill the credits object with something, the button will appear on the main menu title screen! ![The default Monogatari main menu with a visible credits button.](https://cdn.restlessdreams.cloud/c7c718e9-2596-44ed-bc07-095d42538b9a.webp) --- # Components Source: https://monogatari.io/v2/components Section: Documentation Monogatari's interface is built from components — small, self-contained custom elements you can restyle, reconfigure, or replace. This section is the reference for the components you'll customize most often. > [!TIP] > New to components? Start with [the Components building block](/v2/building-blocks/components) > to learn how they work, then come back here for the reference on each one. ## Dialog & text - [Text Box](/v2/components/text-box) — The main dialog box where characters speak. - [Centered Dialog](/v2/components/centered-dialog) — A floating, centered dialog for dramatic moments. - [Type Writer](/v2/components/type-writer) — The animated text engine, with inline effects. - [Dialog Log](/v2/components/dialog-log) — A scrollable history of everything that's been said. ## Menus & navigation - [Main Menu](/v2/components/main-menu) — The game's title-screen menu. - [Quick Menu](/v2/components/quick-menu) — The in-game toolbar (save, load, settings…). - [Choice Container](/v2/components/choice-container) — The buttons shown by the choice action. ## Screens - [Loading Screen](/v2/components/loading-screen) — The asset-preloading progress screen. - [Main Screen](/v2/components/main-screen) — The root game-screen container. - [Settings Screen](/v2/components/settings-screen) — Player settings: language, text speed, volume… - [Save Screen](/v2/components/save-screen) — Where players name and store saves. - [Load Screen](/v2/components/load-screen) — Where players pick a save to load. - [Gallery Screen](/v2/components/gallery-screen) — The unlockable image gallery. - [Help Screen](/v2/components/help-screen) — In-game controls and shortcuts. - [Credits Screen](/v2/components/credits) — Your game's credits. - [Language Selection Screen](/v2/components/language-selection-screen) — The pre-game language picker. ## Saving - [Save Slot](/v2/components/save-slot) — A single save/load slot with its preview. ## Inputs & modals - [Text Input](/v2/components/text-input) — Flexible player input (name entry, prompts…). - [Alert Modal](/v2/components/alert-modal) — Confirmation dialogs (quit, delete…). - [Message Modal](/v2/components/message-modal) — Custom message pop-ups shown by the [message action](/v2/script-actions/message). --- # Wait > Wait an amount of time before continuing Source: https://monogatari.io/v2/script-actions/wait Section: Documentation ## Description ```text 'wait [time]' ``` The `wait` action pauses script execution for a specified amount of time or until the player interacts. Once the time has passed (or the player clicks), the game automatically continues to the next statement. Action ID: `Wait` Reversible: Yes Requires User Interaction: Optional (required if no time specified) ## Parameters | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `time` | `number` | Yes | The time in milliseconds to wait before continuing. | ## Behavior ### With Time Parameter When a time value is provided, the game: 1. Blocks all user interaction 2. Waits for the specified duration 3. Automatically advances to the next statement ```javascript monogatari.script({ 'Start': [ 'Hello there! I want you to wait 5 seconds now', 'wait 5000', 'Wow, that was a long time!', 'end' ] }); ``` In this example, after the first dialog is shown and the player clicks to continue, the game waits for 5 seconds (5000 milliseconds) before showing the next dialog. ### Without Time Parameter When no time is provided, the game pauses and waits for user interaction: ```javascript monogatari.script({ 'Start': [ 'Hello there!', 'wait', 'You clicked to continue!', 'end' ] }); ``` This is useful for creating pause points where you want the player to manually advance. ## Time Conversion The `wait` action accepts time in milliseconds. Common conversions: | Duration | Milliseconds | | :--- | :--- | | 1 second | `1000` | | 5 seconds | `5000` | | 10 seconds | `10000` | | 1 minute | `60000` | | 0.5 seconds | `500` | ## Error Handling If an invalid (non-numeric) time value is provided, the engine will display an error: ```javascript // This will show an error 'wait abc' ``` The error message will indicate the invalid time value and the location in your script. ## Examples ### Dramatic Pause ```javascript monogatari.script({ 'Start': [ 'y The truth is...', 'wait 2000', 'y I\'ve always loved you.', 'end' ] }); ``` ### Scene Transition Delay ```javascript monogatari.script({ 'Start': [ 'show scene black with fadeIn', 'wait 1000', 'show scene bedroom with fadeIn', 'y Where am I?', 'end' ] }); ``` ### Timed Event Sequence ```javascript monogatari.script({ 'Start': [ 'play sound thunder', 'wait 500', 'show scene lightning with flash', 'wait 200', 'show scene dark_room', 'y What was that?!', 'end' ] }); ``` ## Technical Details - During a timed wait, the `block` global is set to `true`, preventing user interaction - When the time elapses, `block` is set back to `false` - The action uses `setTimeout` internally for timing ## Related Actions - [End](/v2/script-actions/end) - End the game - [Jump](/v2/script-actions/jump) - Jump to another label --- # Vibrate > Make the player's device vibrate Source: https://monogatari.io/v2/script-actions/vibrate Section: Documentation ## Description ```javascript 'vibrate <pattern>' ``` The `vibrate` action allows you to make the player's device vibrate on a given pattern. By vibration we refer to actual vibration, not shaking the screen so this is only supported on mobile devices with such capabilities. If this feature is not supported on the player's device, nothing will happen and the game will continue with it's normal flow. Action ID: `Vibrate` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | pattern | `numbers` | No | List of space separated times in milliseconds. While there's no limit on how large a pattern can be, at least one time is required. | ## Single Vibration You can make the device vibrate only once, for example, the following will make it vibrate for 200ms and then stop. ```javascript monogatari.script ({ 'Start': [ 'vibrate 200' 'end' ] }); ``` ## Pattern Vibration You can also make the device vibrate following a pattern by providing a list of times, the following will make the device vibrate for 200ms, then 100ms, then 150ms and so on. ```javascript monogatari.script ({ 'Start': [ 'vibrate 200 100 150 50 200 300' 'end' ] }); ``` --- # Unload > Free up memory by unloading unused assets Source: https://monogatari.io/v2/script-actions/unload Section: Documentation ## Description ```text 'unload <type> [asset] [permanent]' 'unload character <id> [sprite] [permanent]' 'unload block <block_id> [permanent]' 'unload all [permanent]' ``` The unload action allows you to release assets from memory when they are no longer needed. This is crucial for managing memory usage in long games or games with many high-resolution assets. Action ID: `Unload` Reversible: No (Reverting does nothing) Requires User Interaction: No ## Parameters | Parameter | Description | | :--- | :--- | | `type` | The category of the asset (see [Supported Categories](#supported-categories) below). | | `asset` | (Optional) The specific asset to unload. If omitted, all assets of the specified type will be unloaded. | | `id` | When unloading a character, the character's ID. | | `sprite` | (Optional) When unloading a character, the specific sprite to unload. If omitted, all sprites for the character are unloaded. | | `block_id` | When using `unload block`, the ID of the preload block to unload. | | `all` | Special keyword to unload ALL cached assets. | | `permanent` | (Optional) If included, audio assets will also be removed from persistent storage (IndexedDB). | ## Supported Categories The unload action supports the same categories as the [Preload](/v2/script-actions/preload) action: ### Default Audio Categories - `music` - Background music tracks - `sounds` or `sound` - Sound effects - `voices` or `voice` - Voice clips ### Default Image Categories - `scenes` or `scene` - Scene backgrounds - `images` or `image` - General images - `characters` - Character sprites (uses special syntax, see examples) Note: Singular forms (`sound`, `voice`, `scene`, `image`) are aliases for their plural counterparts. ## Examples ### Unload a specific song ```javascript 'unload music theme_song' ``` ### Unload all scenes ```javascript 'unload scenes' ``` ### Unload a specific character sprite ```javascript 'unload character y happy' ``` ### Unload all sprites for a character ```javascript 'unload character y' ``` ### Unload a block of assets ```javascript 'unload block Chapter1' ``` ### Unload everything (e.g., at end of chapter) ```javascript 'unload all' ``` ## The `permanent` Flag By default, unload only removes assets from the in-memory cache. For audio assets, the decoded audio buffers are also stored in IndexedDB for faster loading in future sessions. Adding the `permanent` flag will also remove audio assets from IndexedDB: ```javascript // Only removes from memory cache (will reload faster next time from IndexedDB) 'unload music theme_song' // Removes from both memory AND IndexedDB (will need to re-download and decode) 'unload music theme_song permanent' // Clear all audio from persistent storage 'unload all permanent' ``` This is useful when: - The player has completed a section and won't return - You want to free up storage space - You're updating assets and need to force a fresh download ## Memory Management Best Practices ### Chapter-based Unloading For games with distinct chapters or scenes, use preload blocks and unload them when no longer needed: ```javascript monogatari.action('Preload').blocks({ 'Chapter1': { music: ['intro_theme', 'peaceful'], scenes: ['hometown', 'school'] }, 'Chapter2': { music: ['dramatic', 'battle'], scenes: ['castle', 'dungeon'] } }); // In your script monogatari.script({ 'Chapter1End': [ 'The hero leaves their hometown...', 'unload block Chapter1', 'preload block Chapter2 blocking', 'jump Chapter2Start' ] }); ``` ### Unloading Unused Characters When characters leave the story permanently: ```javascript 'y:happy The adventure continues without me. Goodbye!', 'hide character y', 'unload character y' // Frees all y's sprites from memory ``` ### Full Memory Clear At major story transitions: ```javascript 'unload all', 'preload block NewArc blocking', 'show scene new_beginning' ``` ## Related Actions - [Preload](/v2/script-actions/preload) - Load assets into memory before they're needed --- # Stop Voice > Stop playing voice audio Source: https://monogatari.io/v2/script-actions/stop-voice Section: Documentation ## Description ```javascript 'stop voice [voice_id] [with fade <time>]' ``` The stop voice action will let you stop either all voices currently playing or only one in specific. To learn more about voices, read the [Play Voice documentation](/v2/script-actions/play-voice). Note: Voice audio is automatically stopped when the player advances to the next statement. This action is useful when you want to stop a voice before the player proceeds, or when you have looping voice audio. Action ID: `Stop` Reversible: Yes (restores the previously playing voices from history) Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | voice\_id | `string` | Optional. The name of the specific voice you want to stop. If omitted, all voices will be stopped. | | fade | `number` | Optional. Fade out time in seconds. | ## Examples ### Stop a Specific Voice The following will stop a specific voice, identified by its name. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_002 with loop', 'The previous voice will be repeating itself over and over', 'play voice dialog_001', 'Two voices are currently playing', 'stop voice dialog_002', 'Now the first one has stopped and the second one will stop as soon as it ends', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3', 'dialog_002': 'dialog_file_2.mp3' }); ``` ### Stop All Voices The following will stop all voices currently playing. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_002 with loop', 'The previous voice will be repeating itself over and over', 'play voice dialog_001', 'Two voices are currently playing', 'stop voice', 'No voice is playing now', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3', 'dialog_002': 'dialog_file_2.mp3' }); ``` ### Fade Out Effect The following will stop the voice with a fade out effect. You can also use a fade out effect when stopping all voices. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_002 with loop', 'The previous voice will be repeating itself over and over', 'play voice dialog_001', 'Two voices are currently playing', 'stop voice dialog_002 with fade 2', 'The looping voice fades out...', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3', 'dialog_002': 'dialog_file_2.mp3' }); ``` ### Fade Out All Voices ```javascript 'stop voice with fade 3' // Fade out all voices over 3 seconds ``` ## Related Actions - [Play Voice](/v2/script-actions/play-voice) - Play voice audio - [Pause](/v2/script-actions/pause) - Pause playing media (can be resumed later) --- # Stop Sound > Stop playing sound effects Source: https://monogatari.io/v2/script-actions/stop-sound Section: Documentation ## Description ```javascript 'stop sound [sound_id] [with fade <time>]' ``` The stop sound action will let you stop either all sounds currently playing or only one in specific. To learn more about sounds, read the [Play Sound documentation](/v2/script-actions/play-sound). Action ID: `Stop` Reversible: Yes (restores the previously playing sounds from history) Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | sound\_id | `string` | Optional. The name of the specific sound you want to stop. If omitted, all sounds will be stopped. | | fade | `number` | Optional. Fade out time in seconds. | ## Examples ### Stop a Specific Sound The following will stop a specific sound, identified by its name. Script ```javascript monogatari.script({ 'Start': [ 'play sound night with loop', 'play sound fireCracks with loop', 'Two sounds are currently playing', 'stop sound fireCracks', 'I guess someone put out the fire, only the night sounds are heard now', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'fireCracks': 'fire-cracks.mp3', 'night': 'night.mp3' }); ``` ### Stop All Sounds The following will stop all sounds currently playing. Script ```javascript monogatari.script({ 'Start': [ 'play sound night with loop', 'play sound fireCracks with loop', 'Two sounds are currently playing', 'stop sound', 'It really is a silent night, nothing is heard anymore', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'fireCracks': 'fire-cracks.mp3', 'night': 'night.mp3' }); ``` ### Fade Out Effect The following will stop the sound with a fade out effect. You can also use a fade out effect when stopping all sounds. Script ```javascript monogatari.script({ 'Start': [ 'play sound night with loop', 'play sound fireCracks with loop', 'Two sounds are currently playing', 'stop sound fireCracks with fade 12', 'The fire slowly dies down...', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'fireCracks': 'fire-cracks.mp3', 'night': 'night.mp3' }); ``` ### Fade Out All Sounds ```javascript 'stop sound with fade 3' // Fade out all sounds over 3 seconds ``` ## Related Actions - [Play Sound](/v2/script-actions/play-sound) - Play sound effects - [Pause](/v2/script-actions/pause) - Pause playing media (can be resumed later) --- # Stop Music > Stop playing music Source: https://monogatari.io/v2/script-actions/stop-music Section: Documentation ## Description ```javascript 'stop music [music_id] [with fade <time>]' ``` The stop music action will let you stop either all music currently playing or only one in specific. To learn more about music, read the [Play Music documentation](/v2/script-actions/play-music). Action ID: `Stop` Reversible: Yes (restores the previously playing music from history) Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | music\_id | `string` | Optional. The name of the specific music you want to stop. If omitted, all music will be stopped. | | fade | `number` | Optional. Fade out time in seconds. | ## Examples ### Stop a Specific Music The following will stop a specific music track, identified by its name. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with loop', 'play music mystery with loop', 'Two songs are currently playing', 'stop music mainTheme', 'Only the mystery song is playing now', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3', 'mystery': 'mysterious_song.ogg' }); ``` ### Stop All Music The following will stop all music currently playing. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with loop', 'play music mystery with loop', 'Two songs are currently playing', 'stop music', 'No music is playing anymore', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3', 'mystery': 'mysterious_song.ogg' }); ``` ### Fade Out Effect The following will stop the music with a fade out effect. You can also use a fade out effect when stopping all music. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with loop', 'play music mystery with loop', 'Two songs are currently playing', 'stop music mystery with fade 5', 'The mystery music is fading out over 5 seconds', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3', 'mystery': 'mysterious_song.ogg' }); ``` ### Fade Out All Music ```javascript 'stop music with fade 3' // Fade out all music over 3 seconds ``` ## Related Actions - [Play Music](/v2/script-actions/play-music) - Play background music - [Pause](/v2/script-actions/pause) - Pause playing media (can be resumed later) --- # Show Video > Display videos in your visual novel Source: https://monogatari.io/v2/script-actions/show-video Section: Documentation ## Description ```javascript 'show video <video_id> <mode> [with <properties>]' ``` The video action allows you to show videos in your visual novel in different display modes. Action ID: `Video` Reversible: Yes Requires User Interaction: Depends on mode and properties. Blocking modes (`modal`, `immersive`, `fullscreen`) wait for video completion unless `close` property is used. ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | video_id | `string` | The ID of a video asset previously declared | | mode | `string` | Display mode: `modal`, `displayable`, `background`, `immersive`, or `fullscreen` | ## Display Modes | Mode | Description | Blocks Game | | :--- | :--- | :--- | | `modal` | Shows video in a modal overlay | Yes | | `displayable` | Shows video as an element on the game screen | No | | `background` | Shows video as the background behind characters | No | | `immersive` | Covers the full game screen | Yes | | `fullscreen` | Attempts fullscreen mode (falls back to `immersive` if denied) | Yes | ## Properties | Property | Description | | :--- | :--- | | `controls` | Shows video controls (play, pause, seeking) to the player | | `close` | Automatically removes the video when it ends | | `loop` | Makes the video loop continuously (overrides `close`) | ## Asset Declaration To play a video, add the file to your `assets/videos/` directory and declare it: ```javascript monogatari.assets('videos', { 'intro': 'intro.mp4', 'ending': 'ending_credits.mp4', 'rain': 'rain_loop.webm' }); ``` ### Supported Formats MP4 is recommended for maximum browser compatibility. Other formats: | Format | Browser Support | | :--- | :--- | | MP4 (H.264) | All modern browsers | | WebM | Chrome, Firefox, Edge | | Ogg | Chrome, Firefox | See the [MDN compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility) for detailed browser support. ## Examples ### Modal Video Shows a video in a modal that blocks game progression: ```javascript monogatari.script({ 'Start': [ 'show video intro modal', 'The intro has finished.', 'end' ] }); ``` ### Background Video Use a video as an animated background: ```javascript monogatari.script({ 'Start': [ 'show video rain background with loop', 'e The rain keeps falling...', 'hide video rain', 'end' ] }); ``` ### Auto-Close Video Video that automatically closes when finished: ```javascript monogatari.script({ 'Start': [ 'show video cutscene immersive with close', // Game continues automatically after video ends 'e That was intense!', 'end' ] }); ``` ### Video with Controls Let the player control playback: ```javascript monogatari.script({ 'Start': [ 'show video tutorial modal with controls', 'Did you understand the tutorial?', 'end' ] }); ``` ### Fullscreen Video Attempts to play in fullscreen (falls back to immersive if permission denied): ```javascript monogatari.script({ 'Start': [ 'show video ending fullscreen with close', 'Thanks for playing!', 'end' ] }); ``` ### Displayable Video Shows video as an element without blocking the game: ```javascript monogatari.script({ 'Start': [ 'show video news_broadcast displayable', 'e Look at what\'s on TV!', 'hide video news_broadcast with fadeOut', 'end' ] }); ``` ## Behavior Notes - Blocking modes (`modal`, `immersive`, `fullscreen`): The game waits for the video to end before proceeding, unless `close` is specified - Non-blocking modes (`background`, `displayable`): The game continues immediately - Loop + Close: If both are specified, `loop` takes priority and the video won't auto-close - Volume: Video volume respects the player's Video volume preference setting ## Related Actions - [Hide Video](/v2/script-actions/hide-video) - Stop and remove a video - [Show Scene](/v2/script-actions/show-scene) - Change background (static images) - [Play Music](/v2/script-actions/play-music) - Background audio --- # Show Scene > Change the background Source: https://monogatari.io/v2/script-actions/show-scene Section: Documentation ## Description ```javascript 'show scene <resource> [with [animations] [classes] [properties]]' ``` The `scene` action will change the background and clear the screen, removing all characters, images and text currently displayed. Action ID: `Scene` Reversible: Yes Requires User Interaction: No ## Parameters <table> <thead> <tr> <th style="text-align:left">Name</th> <th style="text-align:left">Type</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align:left">resource</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left"> <p>The resource to use as the background for the scene. This resource may be one of the following:</p> <ul> <li><em>Scene ID</em>: The ID of a scene asset previously defined.</li> <li><em>CSS Property</em>: Any valid non-spaced value for the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/background">background CSS property</a>.</li> </ul> </td> </tr> <tr> <td style="text-align:left">animations</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated animation names with which the scene will be shown.</td> </tr> <tr> <td style="text-align:left">classes</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated CSS class names that will be added to the background element. You can create custom classes on your CSS and add them to your background dynamically using this list.</td> </tr> <tr> <td style="text-align:left">properties</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated properties with their respective value.</td> </tr> </tbody> </table> ### Properties The following is a comprehensive list of the properties available for you to modify certain behaviors of the scene action. | Property Name | Type | Description | | :--- | :--- | :--- | | duration | `string` | The duration for the animations used. The value for this property must be a non-spaced valid value for the [`animation-duration`](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-duration) CSS property. | ## Using an Image as the Background If you want to use an image for the background, remember you first have to declare your image assets and place all your files under the `assets/scenes/` directory. Script: ```javascript monogatari.script ({ 'Start': [ 'show scene mountain', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` ### Using CSS properties as the background If you'll use CSS to set a custom background, you can use any valid non-spaced value for the [`background-image`](https://developer.mozilla.org/en-US/docs/Web/CSS/background) or [`background-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) CSS properties. Using CSS is perfect for when you want your background to be a solid color. Here are some valid statements: ```javascript monogatari.script ({ 'Start': [ 'show scene #fff', 'show scene rgb(0, 0, 0)', 'show scene url("assets/scenes/mountain.png")', 'end' ] }); ``` ### Using Animations Monogatari comes with some built-in animations ready for you to use, you can see the list of animations and visualize them [here](https://daneden.github.io/animate.css/). Using animations is as simple as indicating their name! Script: ```javascript monogatari.script ({ 'Start': [ 'show scene sea with fadeIn', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` #### Modifying an animation duration The following will set the background to a solid color using a CSS value and modify the duration of the _fadeIn_ animation to 20 seconds. ```javascript monogatari.script ({ 'Start': [ 'show scene #424242 with fadeIn duration 20s', 'end' ] }); ``` #### Creating a custom animation You can also use CSS to create your own animations, you'll have to apply them to a CSS class and then use the scene statement as follows: For example, note the following CSS code creating a simple Ken Burn Animation: Script: ```javascript monogatari.script ({ 'Start': [ 'show scene mountain with ken-burn', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` CSS: ```css .ken-burn { animation-name: ken-burns; /* Name of the animation to use / animation-duration: 30s; animation-iteration-count: infinite; / 1 if it should only move once / animation-timing-function: ease; animation-fill-mode: forwards; animation-delay: 0s; -moz-transition: ease 1s all; -o-transition: ease 1s all; -webkit-transition: ease 1s all; transition: ease 1s all; } @keyframes ken-burns { 0% { transform: translateX(0); } 50% { transform: translateX(-500px); } 100% { transform: translateX(0px); } } ``` ## Behavior When a scene is shown: 1. The background is changed 2. All characters are removed from the screen 3. All images are removed from the screen 4. The text box is cleared This makes `show scene` ideal for scene transitions where you want a clean slate. If you only want to change the background without removing elements, use [Show Background](/v2/script-actions/show-background) instead. ## Related Actions - [Show Background](/v2/script-actions/show-background) - Change background without clearing elements - [Show Character](/v2/script-actions/characters) - Display character sprites - [Show Image](/v2/script-actions/show-image) - Display images --- # Show Particles > Show a particle system animation Source: https://monogatari.io/v2/script-actions/particles Section: Documentation ## Description ```javascript 'show particles <particles_id>' ``` The `particles` action let's you show amazing animations using particle systems. A particle system is useful when you want to add dynamic elements such as snow, stars, rain etc. and can be an awesome addition for your game! To hide the particle systems, read the [Hide Particles documentation](/v2/script-actions/hide-particles). Action ID: Particles Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | particles\_id | `string` | The name of the particles system you want to show. These must be declared beforehand using this action configuration functions. | ## Configuration To use a particle system, you must first declare it with all of it's characteristics. To do so, the particles action has a configuration function where you can define your id for each particle system and their configuration on a JSON Object. ```javascript Monogatari.action ('Particles').particles ({ '<particles_id>': ParticlesJSONObject }); ``` This action uses the [Particles.js library](https://github.com/VincentGarreau/particles.js/), reading their documentation you can find more information about it and also more information on how to create a custom particle system. ### Samples Here are some examples that may be useful and also provide a good start point: Snow ```javascript Monogatari.action('Particles').particles({ 'snow': { 'particles': { 'number': { 'value': 400, 'density': { 'enable': true, 'value_area': 800 } }, 'color': { 'value': '#fff' }, 'shape': { 'type': 'circle', 'stroke': { 'width': 0, 'color': '#000000' }, 'polygon': { 'nb_sides': 5 }, 'image': { 'src': 'img\/github.svg', 'width': 100, 'height': 100 } }, 'opacity': { 'value': 0.5, 'random': true, 'anim': { 'enable': false, 'speed': 1, 'opacity_min': 0.1, 'sync': false } }, 'size': { 'value': 10, 'random': true, 'anim': { 'enable': false, 'speed': 40, 'size_min': 0.1, 'sync': false } }, 'line_linked': { 'enable': false, 'distance': 500, 'color': '#ffffff', 'opacity': 0.4, 'width': 2 }, 'move': { 'enable': true, 'speed': 6, 'direction': 'bottom', 'random': false, 'straight': false, 'out_mode': 'out', 'bounce': false, 'attract': { 'enable': false, 'rotateX': 600, 'rotateY': 1200 } } }, 'interactivity': { 'detect_on': 'canvas', 'events': { 'onhover': { 'enable': true, 'mode': 'bubble' }, 'onclick': { 'enable': true, 'mode': 'repulse' }, 'resize': true }, 'modes': { 'grab': { 'distance': 400, 'line_linked': { 'opacity': 0.5 } }, 'bubble': { 'distance': 400, 'size': 4, 'duration': 0.3, 'opacity': 1, 'speed': 3 }, 'repulse': { 'distance': 200, 'duration': 0.4 }, 'push': { 'particles_nb': 4 }, 'remove': { 'particles_nb': 2 } } }, 'retina_detect': true } }); ``` Night Sky ```javascript Monogatari.action('Particles').particles({ 'stars': { 'particles': { 'number': { 'value': 355, 'density': { 'enable': true, 'value_area': 789.1476416322727 } }, 'color': { 'value': '#ffffff' }, 'shape': { 'type': 'circle', 'stroke': { 'width': 0, 'color': '#000000' }, 'polygon': { 'nb_sides': 5 }, 'image': { 'src': '', 'width': 100, 'height': 100 } }, 'opacity': { 'value': 0.48927153781200905, 'random': false, 'anim': { 'enable': true, 'speed': 0.2, 'opacity_min': 0, 'sync': false } }, 'size': { 'value': 2, 'random': true, 'anim': { 'enable': true, 'speed': 2, 'size_min': 0, 'sync': false } }, 'line_linked': { 'enable': false, 'distance': 150, 'color': '#ffffff', 'opacity': 0.4, 'width': 1 }, 'move': { 'enable': true, 'speed': 0.2, 'direction': 'none', 'random': true, 'straight': false, 'out_mode': 'out', 'bounce': false, 'attract': { 'enable': false, 'rotateX': 600, 'rotateY': 1200 } } }, 'interactivity': { 'detect_on': 'canvas', 'events': { 'onhover': { 'enable': true, 'mode': 'bubble' }, 'onclick': { 'enable': true, 'mode': 'push' }, 'resize': true }, 'modes': { 'grab': { 'distance': 400, 'line_linked': { 'opacity': 1 } }, 'bubble': { 'distance': 83.91608391608392, 'size': 1, 'duration': 3, 'opacity': 1, 'speed': 3 }, 'repulse': { 'distance': 200, 'duration': 0.4 }, 'push': { 'particles_nb': 4 }, 'remove': { 'particles_nb': 2 } } }, 'retina_detect': true } }); ``` Fireflies ```javascript Monogatari.action('Particles').particles({ 'fireflies': { 'particles': { 'number': { 'value': 202, 'density': { 'enable': true, 'value_area': 800 } }, 'color': { 'value': '#0bd318' }, 'shape': { 'type': 'circle', 'stroke': { 'width': 0, 'color': '#000000' }, 'polygon': { 'nb_sides': 5 }, 'image': { 'src': 'img/github.svg', 'width': 100, 'height': 100 } }, 'opacity': { 'value': 0.9299789953020032, 'random': true, 'anim': { 'enable': true, 'speed': 1, 'opacity_min': 0, 'sync': false } }, 'size': { 'value': 3, 'random': true, 'anim': { 'enable': false, 'speed': 4, 'size_min': 0.3, 'sync': false } }, 'line_linked': { 'enable': false, 'distance': 150, 'color': '#ffffff', 'opacity': 0.4, 'width': 1 }, 'move': { 'enable': true, 'speed': 3.017060304327615, 'direction': 'none', 'random': true, 'straight': false, 'out_mode': 'out', 'bounce': false, 'attract': { 'enable': false, 'rotateX': 1042.21783956259, 'rotateY': 600 } } }, 'interactivity': { 'detect_on': 'canvas', 'events': { 'onhover': { 'enable': true, 'mode': 'bubble' }, 'onclick': { 'enable': true, 'mode': 'repulse' }, 'resize': true }, 'modes': { 'grab': { 'distance': 400, 'line_linked': { 'opacity': 1 } }, 'bubble': { 'distance': 250, 'size': 0, 'duration': 2, 'opacity': 0, 'speed': 3 }, 'repulse': { 'distance': 400, 'duration': 0.4 }, 'push': { 'particles_nb': 4 }, 'remove': { 'particles_nb': 2 } } }, 'retina_detect': true } }); ``` Fire Sparks ```javascript Monogatari.action('Particles').particles({ 'fireSparks': { 'particles': { 'number': { 'value': 400, 'density': { 'enable': true, 'value_area': 3000 } }, 'color': { 'value': '#fc0000' }, 'shape': { 'type': 'circle', 'stroke': { 'width': 0, 'color': '#000000' }, 'polygon': { 'nb_sides': 3 }, 'image': { 'src': 'img/github.svg', 'width': 100, 'height': 100 } }, 'opacity': { 'value': 0.5, 'random': true, 'anim': { 'enable': false, 'speed': 1, 'opacity_min': 0.1, 'sync': false } }, 'size': { 'value': 2, 'random': true, 'anim': { 'enable': true, 'speed': 5, 'size_min': 0, 'sync': false } }, 'line_linked': { 'enable': false, 'distance': 500, 'color': '#ffffff', 'opacity': 0.4, 'width': 2 }, 'move': { 'enable': true, 'speed': 7.8914764163227265, 'direction': 'top', 'random': true, 'straight': false, 'out_mode': 'out', 'bounce': false, 'attract': { 'enable': false, 'rotateX': 600, 'rotateY': 1200 } } }, 'interactivity': { 'detect_on': 'canvas', 'events': { 'onhover': { 'enable': false, 'mode': 'bubble' }, 'onclick': { 'enable': false, 'mode': 'repulse' }, 'resize': true }, 'modes': { 'grab': { 'distance': 400, 'line_linked': { 'opacity': 0.5 } }, 'bubble': { 'distance': 400, 'size': 4, 'duration': 0.3, 'opacity': 1, 'speed': 3 }, 'repulse': { 'distance': 200, 'duration': 0.4 }, 'push': { 'particles_nb': 4 }, 'remove': { 'particles_nb': 2 } } }, 'retina_detect': true } }); ``` You can also play with the [Particles.js interactive tool](https://vincentgarreau.com/particles.js/) to create your own particle systems. ## Examples For this examples, we'll assume you've used one of the sample configurations provided. Showing a particle system is as simple as: ```javascript Monogatari.script ({ 'Start': [ 'show particles snow', 'end' ] }); ``` --- # Show Notification > Show a notification to the player Source: https://monogatari.io/v2/script-actions/notifications Section: Documentation ## Description ```javascript 'show notification <notification_id> [time]' ``` The `notification` action shows a system notification to the player. Notifications are useful for achievement unlocks, event alerts, or other non-intrusive messages. Action ID: `Notification` Reversible: Yes Requires User Interaction: If no time is provided, the player must dismiss the notification, but the game continues without waiting. ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | notification_id | `string` | The ID of the notification to show (must be declared beforehand) | | time | `number` | Optional. Time in milliseconds before auto-dismiss | ## Configuration Declare notifications with their properties before using them: ```javascript monogatari.action('Notification').notifications({ '<notification_id>': { title: '', body: '', icon: '' } }); ``` ### Properties | Name | Type | Description | | :--- | :--- | :--- | | title | `string` | The notification title (required) | | body | `string` | The notification body text | | icon | `string` | Path to an image for the notification icon | ## Browser Permissions > [!NOTE] > Notifications use the browser's native Notification API. The player must grant permission when prompted. If denied, notifications won't be shown but the game continues normally. ## Examples ### Simple Notification A notification the player dismisses manually: Configuration: ```javascript monogatari.action('Notification').notifications({ 'Welcome': { title: 'Welcome!', body: 'Thanks for playing our game!', icon: 'assets/icons/game_icon.png' } }); ``` Script: ```javascript monogatari.script({ 'Start': [ 'show notification Welcome', 'e Let\'s begin our adventure!', 'end' ] }); ``` ### Timed Notification A notification that auto-dismisses after 5 seconds (5000ms): Configuration: ```javascript monogatari.action('Notification').notifications({ 'Achievement': { title: 'Achievement Unlocked!', body: 'You found the secret passage!', icon: 'assets/icons/trophy.png' } }); ``` Script: ```javascript monogatari.script({ 'SecretRoom': [ 'show notification Achievement 5000', 'e Wow, I never knew this was here!', 'end' ] }); ``` ### Multiple Notifications Configuration: ```javascript monogatari.action('Notification').notifications({ 'NewItem': { title: 'New Item', body: 'You received a mysterious key.', icon: 'assets/icons/key.png' }, 'QuestComplete': { title: 'Quest Complete', body: 'The mystery has been solved!', icon: 'assets/icons/check.png' }, 'Save': { title: 'Game Saved', body: 'Your progress has been saved.', icon: 'assets/icons/save.png' } }); ``` Script: ```javascript monogatari.script({ 'FindKey': [ 'show notification NewItem 3000', 'e What\'s this? A key!', 'jump SolveMyster' ], 'SolveMystery': [ 'show notification QuestComplete 5000', 'e I finally figured it out!', 'end' ] }); ``` ### Using Variable Interpolation Notification text supports storage variable interpolation: Configuration: ```javascript monogatari.action('Notification').notifications({ 'LevelUp': { title: 'Level Up!', body: '{{player.name}} reached level {{player.level}}!', icon: 'assets/icons/star.png' } }); ``` ## Behavior Notes - The game does not wait for notifications to be dismissed - If permission is denied, no error is thrown—the game continues - Notification appearance depends on the browser and OS - Icons should be appropriate size (usually 64x64 or 128x128 pixels) ## Error Handling The action will show an error if: - The notification ID doesn't exist in the configuration - The time parameter is not a valid number ## Related Actions - [Show Message](/v2/script-actions/message) - In-game modal messages - [Choices](/v2/script-actions/choices) - Present options to players --- # Show Message > Show a message Source: https://monogatari.io/v2/script-actions/message Section: Documentation ## Description ```javascript 'show message <message_id>' ``` The `message` action let's you show a message to the player. A message is a nice way of showing something that requires more text such as an email or instructions. You could also use it as a mailbox or something of the sorts in your game. Each message has a close button so the user is able to close it when he's finished reading it. Action ID: `Message` Reversible: Yes Requires User Interaction: Yes, the user needs to close the message before continuing. ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | message\_id | `string` | The name of the message you want to show. These must be declared beforehand using this action configuration functions. | ## Configuration To show a message, you must first declare it with all of it's characteristics. To do so, the message action has a configuration function where you can define your id or name for each message and their respective information. ```javascript monogatari.action ('Message').messages ({ '<message_id>': { title: '', subtitle: '', body: '' } }); ``` ### Properties | Name | Type | Description | | :--- | :--- | :--- | | title | `string` | The title of the message | | subtitle | `string` | A subtitle for the message | | body | `string` | The body or contents of the message | ## Examples ### Text Message The following script will show a simple text message: Script: ```javascript monogatari.script ({ 'Start': [ 'show message SampleWriting', 'end' ] }); ``` Message Configuration: ```javascript monogatari.action ('Message').messages ({ 'SampleWriting':{ title: 'Some sample writing', subtitle: 'From Evelyn', body:'Just look how easy it is!' } }); ``` ### HTML Message You can also include HTML on your message, the following script and configuration will show a message with HTML on it. Script: ```javascript monogatari.script ({ 'Start': [ 'show message SampleHTML', 'end' ] }); ``` Message Configuration: ```javascript monogatari.action ('Message').messages ({ 'SampleHTML':{ title: 'Some sample writing', subtitle: 'From Evelyn', body: ` <p>This message is being formatted with HTML</p> <img src="assets/images/message.png"> ` } }); ``` ### Custom Button Text You can customize the close button text using the `actionString` property: ```javascript monogatari.action ('Message').messages ({ 'Letter': { title: 'A Letter From Home', subtitle: 'From Mom', body: 'Hope you\'re doing well! Come visit soon.', actionString: 'Close Letter' } }); ``` ### Adding CSS Classes You can pass additional CSS classes after the message ID to style specific messages: ```javascript 'show message ImportantNote urgent highlighted' ``` ## Related Actions - [Input](/v2/script-actions/input) - Get player input - [Choices](/v2/script-actions/choices) - Present options to players --- # Show Image > Show an image on screen Source: https://monogatari.io/v2/script-actions/show-image Section: Documentation ## Description ```javascript 'show image <resource> [at <position>] [with <animation> [classes] [properties]]' ``` The `show image` action allows you to display an image on screen. For character sprites, use the [Show Character action](/v2/script-actions/characters) instead. Action ID: `Show::Image` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | resource | `string` | Either an asset ID declared in `monogatari.assets('images', {...})` or a filename in the images directory | | position | `string` | Optional. CSS class for positioning (e.g., `center`, `left`, `right`) | | animation | `string` | Optional. Animation name from [Animate.css](https://daneden.github.io/animate.css/) | | classes | `string` | Optional. Additional CSS classes to apply | | properties | `string` | Optional. Properties like `duration` | ## Properties | Property | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` (e.g., `duration 2s`) | ## Asset Declaration Declare image assets in your `script.js` or `main.js`: ```javascript monogatari.assets('images', { 'flower': 'flower.png', 'logo': 'company_logo.png', 'item_sword': 'items/sword.png' }); ``` Images are loaded from `assets/images/` by default. ## Examples ### Using Declared Assets ```javascript 'show image flower with fadeIn' ``` ### Using Filename Directly If you haven't declared an asset, use the filename: ```javascript 'show image flower.png with fadeIn' ``` ### Positioning ```javascript // Center (default) 'show image logo with fadeIn' // Specific position 'show image flower at left with fadeIn' 'show image flower at right with slideInRight' ``` ### Animation Duration ```javascript 'show image logo with fadeIn duration 3s' ``` ### Multiple Classes ```javascript 'show image flower at center with fadeIn myCustomClass' ``` ## Image Caching The action checks if the image has been preloaded and cached. If cached, it clones the cached image for faster display. ## Complete Example ```javascript monogatari.assets('images', { 'flower': 'flower.png', 'butterfly': 'butterfly.png' }); monogatari.script({ 'Start': [ 'show scene garden with fadeIn', 'show image flower at left with fadeIn', 'The garden is beautiful.', 'show image butterfly at right with bounceIn duration 2s', 'A butterfly appears!', 'hide image butterfly with fadeOut', 'hide image flower with fadeOut', 'end' ] }); ``` ## Related Actions - [Hide Image](/v2/script-actions/hide-image) - Remove an image from screen - [Show Character](/v2/script-actions/characters) - Display character sprites - [Show Scene](/v2/script-actions/show-scene) - Change the background --- # Show Character Layer > Control individual layers of a character sprite Source: https://monogatari.io/v2/script-actions/character-layers Section: Documentation > [!WARNING] > This feature is currently Experimental. Syntax and behavior may change in future versions. > Requires `ExperimentalFeatures` to be enabled in settings. ## Description The Character Layer actions allow you to manipulate specific parts (layers) of a composite character sprite independently. This is useful for paper-doll systems where you want to change expressions, outfits, or accessories without replacing the entire character image. ## Actions | Action | ID | Description | | :--- | :--- | :--- | | Show Layer | `Show::Character::Layer` | Display or change a specific layer | | Hide Layer | `Hide::Character::Layer` | Remove a specific layer | Reversible: Yes Requires User Interaction: No ## Character Setup To use layers, your character definition must include: 1. `layers` - An array defining the layer order (bottom to top, determines z-index) 2. `layer_assets` - An object mapping layer names to their available sprites ```javascript monogatari.characters({ 'y': { name: 'Yui', directory: 'yui', // Define layer order (bottom to top) layers: ['base', 'clothes', 'face', 'accessories'], // Define available sprites for each layer layer_assets: { base: { body: 'base_body.png' }, clothes: { uniform: 'clothes_uniform.png', casual: 'clothes_casual.png', swimsuit: 'clothes_swimsuit.png' }, face: { neutral: 'face_neutral.png', happy: 'face_happy.png', sad: 'face_sad.png', angry: 'face_angry.png' }, accessories: { glasses: 'acc_glasses.png', hat: 'acc_hat.png' } }, // Standard sprites can still be used sprites: { normal: 'normal.png' // Fallback non-layered sprite } } }); ``` ### Layer Order The `layers` array determines the z-index of each layer. Layers listed first appear behind layers listed later: ```javascript layers: ['base', 'clothes', 'face', 'accessories'] // ↑ back front ↑ ``` ## Show Layer ```text 'show character <character_id>:<layer> <sprite> [with <animation> [end-<animation>] [classes] [properties]]' ``` Displays a specific sprite on a specific layer for a character. ### Properties | Name | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` | | `transition` | Sets `transition-duration` CSS property. Format: `transition <time>` | | `end-<animation>` | Animation to play when this layer is changed | ### Prerequisites The parent character must be shown first using `show character` before adding layers: ```javascript // First show the character (can be a layered sprite or regular) 'show character y normal', // Then add/modify individual layers 'show character y:face happy' ``` ### Examples Set Yui's face to happy: ```javascript 'show character y:face happy' ``` Change clothes with animation: ```javascript 'show character y:clothes casual with fadeIn' ``` Add glasses with a fade effect: ```javascript 'show character y:accessories glasses with fadeIn duration 0.5s' ``` Prepare exit animation for a layer: ```javascript 'show character y:accessories glasses with fadeIn end-fadeOut' ``` ## Hide Layer ```text 'hide character <character_id>:<layer> [with <animation> [classes] [properties]]' ``` Removes a specific layer from a displayed character. ### Properties | Name | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` | ### Examples Remove Yui's glasses: ```javascript 'hide character y:accessories' ``` Remove glasses with animation: ```javascript 'hide character y:accessories with fadeOut' ``` Remove with custom duration: ```javascript 'hide character y:accessories with fadeOut duration 1s' ``` ## Complete Example ```javascript monogatari.script({ 'Start': [ // Show the character with base layers 'show character y normal at center with fadeIn', // Build up the character layer by layer 'show character y:base body', 'show character y:clothes uniform with fadeIn', 'show character y:face neutral with fadeIn', 'y Hello! I\'m Yui.', // Change expression 'show character y:face happy', 'y Nice to meet you!', // Add accessories 'show character y:accessories glasses with fadeIn duration 0.3s', 'y Let me put on my reading glasses.', // Change clothes 'show character y:clothes casual with fadeIn end-fadeOut', 'y I changed into something more comfortable.', // Remove accessories 'hide character y:accessories with fadeOut', 'y I don\'t need these anymore.', // Change expression 'show character y:face sad', 'y Time to say goodbye...', // Hide the whole character 'hide character y with fadeOut' ] }); ``` ## State Management ### State Character layers are tracked in the engine state: ```javascript // Get current layer states const layers = monogatari.state('characterLayers'); ``` ### History Layer changes are recorded in history for rollback support: ```javascript // Get layer history const history = monogatari.history('characterLayer'); ``` ## Error Handling The actions will show errors if: 1. Character not found: The character ID doesn't exist 2. Layer not shown: Attempting to hide a layer that isn't displayed 3. Parent not shown: Attempting to add a layer when the character isn't displayed ## CSS Styling Layer images are rendered as `<img>` elements inside a wrapper: ```css / Style all layer images / [data-character] [data-layer] { / Custom styles / } / Style a specific layer / [data-character="y"] [data-layer="face"] { / Face layer specific styles / } ``` ## Related Actions - [Show Character](/v2/script-actions/characters) - Display the parent character - [Hide Character](/v2/script-actions/hide-character) - Remove the entire character --- # Show Character > Show a character's sprite Source: https://monogatari.io/v2/script-actions/characters Section: Documentation ## Description ```text 'show character <character_id> <sprite_id> [at <position>] [with <animation> [infinite] [end-<animation>] [classes] [properties]]' ``` The character action allows you to display a character's sprite. For other kind of images, take a look at the [show image action](/v2/script-actions/show-image). Action ID: `Show::Character` Reversible: Yes Requires User Interaction: No ## Character Definition Characters must be defined before they can be shown. Each character has a unique identifier used in scripts: ```javascript monogatari.characters({ 'e': { name: 'Evelyn', color: '#00bfff', directory: 'evelyn', // Subdirectory in assets/characters/ sprites: { normal: 'normal.png', happy: 'happy.png', sad: 'sad.png' } } }); ``` ### Character Properties | Property | Description | | :--- | :--- | | `name` | Display name shown in the text box | | `color` | Color for the character's name (hex, rgb, or rgba) | | `directory` | Subdirectory within `assets/characters/` for sprite images | | `sprites` | Object mapping sprite identifiers to image filenames | | `Face` | Optional side image shown when the character speaks | | `Side` | Optional object mapping side image identifiers for dialog expressions | ## Syntax ### Positions The `at <position>` clause sets where the character appears on screen. If omitted, defaults to `center`. Common positions (CSS classes): - `left` - Left side of the screen - `center` - Center of the screen (default) - `right` - Right side of the screen Custom positions can be defined via CSS. ### Properties These are special properties/classes that can be used when showing a character: | Name | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` (e.g., `duration 2s`) | | `transition` | Sets `transition-duration` CSS property for the `move` class. Format: `transition <time>` | | `move` | Enables smooth movement animation when changing positions | | `end-<animation>` | Specifies an animation to play when the sprite is changed or removed | | `infinite` | Makes the animation loop indefinitely | ## Examples ### Basic Usage Show a character at the center (default position): ```javascript 'show character e normal' ``` Show a character with an animation: ```javascript 'show character e normal with fadeIn' ``` Show a character at a specific position with animation: ```javascript 'show character e normal at center with fadeIn' ``` ### Infinite Animations Make an animation loop continuously: ```javascript 'show character e normal with pulse infinite' ``` ### Duration Control how long an animation takes to complete: ```javascript 'show character e normal with fadeIn duration 20s' ``` ### Move + Transition Smoothly move a character from one position to another: ```javascript 'show character e normal at left', 'show character e normal at right with move transition 6s' ``` The character will move from left to right over 6 seconds. ### Exit Animations Prepare an animation to play when the sprite changes. This creates smooth crossfade effects: ```javascript 'show character e normal with end-fadeOut', 'show character e happy with fadeIn' ``` When changing from `normal` to `happy`, the old sprite will fade out while the new one fades in. ### Complete Example ```javascript monogatari.script({ 'Start': [ 'show character e normal at left with fadeIn', 'e Hello there!', 'show character e happy at center with move transition 1s', 'e I moved to the center!', 'show character e normal with end-fadeOut', 'show character e sad with fadeIn duration 2s', 'e Now I\'m sad...', 'hide character e with fadeOut' ] }); ``` ## Experimental: Layered Sprites > [!WARNING] > This feature requires `ExperimentalFeatures` to be enabled in settings. When experimental features are enabled, you can define composite sprites made of multiple layers: ```javascript monogatari.characters({ 'y': { name: 'Yui', directory: 'yui', sprites: { // Object-based sprites define layers normal: { base: 'base_uniform.png', face: 'face_neutral.png' }, happy: { base: 'base_uniform.png', face: 'face_happy.png' } } } }); ``` Showing a layered sprite works the same as regular sprites: ```javascript 'show character y normal' ``` For individual layer control, see [Character Layers](/v2/script-actions/character-layers). ## Sprite Caching Character sprites that have been preloaded are automatically cached for faster display. When showing a character, the engine checks for cached sprites before loading from disk. To preload character sprites: ```javascript 'preload character e normal' ``` See the [Preload action](/v2/script-actions/preload) for more details. ## Related Actions - [Hide Character](/v2/script-actions/hide-character) - Remove a character from the screen - [Character Layers](/v2/script-actions/character-layers) - Control individual sprite layers - [Show Image](/v2/script-actions/show-image) - Show non-character images --- # Show Background > Show a background without removing any game elements. Source: https://monogatari.io/v2/script-actions/show-background Section: Documentation ## Description ```text 'show background <resource> [with [animations] [classes] [properties]]' ``` The `show background` action will change the background without removing any game elements $as opposed to the [scene action](/v2/script-actions/show-scene)$. This action uses the assets from the scene action so they still need to be declared as scene assets. Action ID: `Show::Background` Reversible: Yes Requires User Interaction: No ## Parameters <table> <thead> <tr> <th style="text-align:left">Name</th> <th style="text-align:left">Type</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align:left">resource</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left"> <p>The resource to use as the background. This resource may be one of the following:</p> <ul> <li><em>Asset ID</em>: The ID of a scene asset previously defined.</li> <li><em>CSS Property</em>: Any valid non-spaced value for the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/background">background CSS property</a>.</li> </ul> </td> </tr> <tr> <td style="text-align:left">animations</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated animation names with which the background will be shown.</td> </tr> <tr> <td style="text-align:left">classes</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated CSS class names that will be added to the background element. You can create custom classes on your CSS and add them to your background dynamically using this list.</td> </tr> <tr> <td style="text-align:left">properties</td> <td style="text-align:left"><code>string</code> </td> <td style="text-align:left">Optional. A list of comma separated properties with their respective value.</td> </tr> </tbody> </table> ### Properties The following is a comprehensive list of the properties available for you to modify certain behaviors of the background action. | Property Name | Type | Description | | :--- | :--- | :--- | | duration | `string` | The duration for the animations used. The value for this property must be a non-spaced valid value for the [`animation-duration`](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-duration) CSS property. | ## Examples ### Using an image as the background If you want to use an image for the background, remember you first have to declare your image assets and place all your files under the `assets/scenes/` directory. Script: ```javascript monogatari.script ({ 'Start': [ 'show background mountain', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` ### Using CSS properties as the background If you'll use CSS to set a custom background, you can use any valid non-spaced value for the [`background-image`](https://developer.mozilla.org/en-US/docs/Web/CSS/background) or [`background-color`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) CSS properties. Using CSS is perfect for when you want your background to be a solid color. Here are some valid statements: ```javascript monogatari.script ({ 'Start': [ 'show background #fff', 'show background rgb(0, 0, 0)', 'show background url("assets/scenes/mountain.png")', 'end' ] }); ``` You can also use CSS gradients for backgrounds. ```javascript monogatari.script ({ 'Start': [ "We're about to show a linear gradient.", "show background linear-gradient(to right, red, yellow)", "Isn't that lovely?", "end" ] }); ``` ### Using Animations Monogatari comes with some built-in animations ready for you to use, you can see the list of animations and visualize them [here](https://daneden.github.io/animate.css/). Using animations is as simple as indicating their name! Script: ```javascript monogatari.script ({ 'Start': [ 'show background sea with fadeIn', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` #### Modifying an animation duration The following will set the background to a solid color using a CSS value and modify the duration of the _fadeIn_ animation to 20 seconds. ```javascript monogatari.script ({ 'Start': [ 'show background #424242 with fadeIn duration 20s', 'end' ] }); ``` #### Creating a custom animation You can also use CSS to create your own animations, you'll have to apply them to a CSS class and then use the show background statement as follows: For example, note the following CSS code creating a simple Ken Burn Animation: Script: ```javascript monogatari.script ({ 'Start': [ 'show background mountain with ken-burn', 'end' ] }); ``` Scene Assets: ```javascript monogatari.assets ('scenes', { 'mountain': 'mountain.png', 'sea': 'sea.png' }); ``` CSS: ```css .ken-burn { animation-name: ken-burns; / Name of the animation to use / animation-duration: 30s; animation-iteration-count: infinite; / 1 if it should only move once / animation-timing-function: ease; animation-fill-mode: forwards; animation-delay: 0s; -moz-transition: ease 1s all; -o-transition: ease 1s all; -webkit-transition: ease 1s all; transition: ease 1s all; } @keyframes ken-burns { 0% { transform: translateX(0); } 50% { transform: translateX(-500px); } 100% { transform: translateX(0px); } } ``` ## Related Actions - [Show Scene](/v2/script-actions/show-scene) - Change background and clear all elements - [Show Character](/v2/script-actions/characters) - Display character sprites - [Show Image](/v2/script-actions/show-image) - Display images --- # Show Canvas Source: https://monogatari.io/v2/script-actions/canvas Section: Documentation ## Description ```javascript 'show canvas <object_id> <mode> [with [...classes]]' ``` Action ID: Canvas Reversible: Yes Requires User Interaction: Depends on the mode the canvas is displayed on ## Parameters <table> <thead> <tr> <th style="text-align:left">Name</th> <th style="text-align:left">Optional</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align:left"><code>object_id</code> </td> <td style="text-align:left">No</td> <td style="text-align:left">The ID of a canvas object previously defined.</td> </tr> <tr> <td style="text-align:left"><code>mode</code> </td> <td style="text-align:left">No</td> <td style="text-align:left"> <p>Defines what way you want to show the canvas like.</p> <p>Possible Values:</p> <ul> <li><code>modal</code> - Shows the canvas as a modal overlay</li> <li><code>displayable</code> - Shows the canvas in the displayable area</li> <li><code>immersive</code> - Shows the canvas covering the full game screen</li> <li><code>background</code> - Shows the canvas as a background for your characters</li> <li><code>character</code> - Shows the canvas in the character display area</li> </ul> </td> </tr> <tr> <td style="text-align:left"><code>...classes</code> </td> <td style="text-align:left">Yes</td> <td style="text-align:left">List of CSS classes to add to the component.</td> </tr> </tbody> </table> ## Canvas Objects ```javascript { layers: [], props: {}, state: {}, start: function (layers, props, state, container) { // In here we do everything we need to start // our canvas and perform the updates // Note: 'this' refers to the Monogatari engine instance }, stop: function (layers, props, state, container) { // Any actions we need to perform to stop the // canvas such as canceling animations and // freeing resources before the element gets removed // Note: 'this' refers to the Monogatari engine instance }, resize: function (layers, props, state, container) { // Perform any actions required when the window // gets resized, it's useful for reacting to this // changes by changing your canvas width and height. // Note: 'this' refers to the Monogatari engine instance }, } ``` <table> <thead> <tr> <th style="text-align:left">Property</th> <th style="text-align:left">Type</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align:left"><code>layers</code> </td> <td style="text-align:left"><code>Array<string></code> </td> <td style="text-align:left"> <p>Most of the times, a single canvas HTML element is not enough to represent all we require and it may not be efficient either since it would have to re-draw all its elements every time we needed to clear it. The layers property is a list of strings (names of layers) that you want your canvas to have. A HTML canvas element with a <code>data-layer</code> property will be created for every layer you list here.</p> <p>If none is provided, a single canvas will be created with a default <code>base</code> layer.</p> <p><strong>Note:</strong> When passed to the <code>start</code>, <code>stop</code>, and <code>resize</code> functions, <code>layers</code> is an object mapping layer names to their corresponding HTMLCanvasElement instances (e.g., <code>{ sky: HTMLCanvasElement, stars: HTMLCanvasElement }</code> or <code>{ base: HTMLCanvasElement }</code>). You can destructure this object in your function parameters.</p> </td> </tr> <tr> <td style="text-align:left"><code>props</code> </td> <td style="text-align:left"><code>object</code> </td> <td style="text-align:left">The props object provides a place to add any static functions or variables you might want to share between your object functions. These are properties that don't change throughout the execution of your canvas object.</td> </tr> <tr> <td style="text-align:left"><code>state</code> </td> <td style="text-align:left"><code>object</code> </td> <td style="text-align:left">The state object provides a place where you can add any variables you wish to share between your object functions. These are properties you expect to change throughout the execution of your canvas object.</td> </tr> <tr> <td style="text-align:left"><code>start</code> </td> <td style="text-align:left"><code>function</code> </td> <td style="text-align:left">The function that will be called right after the HTML element for the canvas is created. In here, you should draw your contents to the layers you setup and setup any update required. The function receives <code>(layers, props, state, container)</code> as parameters, where <code>this</code> refers to the Monogatari engine instance.</td> </tr> <tr> <td style="text-align:left"><code>stop</code> </td> <td style="text-align:left"><code>function</code> </td> <td style="text-align:left">This function will be called by the <code>hide canvas</code> action to stop and remove your canvas. In here you should cancel any animations and free up any resources in use by your canvas. The function receives <code>(layers, props, state, container)</code> as parameters, where <code>this</code> refers to the Monogatari engine instance.</td> </tr> <tr> <td style="text-align:left"><code>resize</code> </td> <td style="text-align:left"><code>function</code> </td> <td style="text-align:left">This function will be called every time the window gets resized, it's useful for reacting to this changes by changing your canvas width and height. The function receives <code>(layers, props, state, container)</code> as parameters, where <code>this</code> refers to the Monogatari engine instance. Note: This function is only called for canvas objects with <code>background</code> or <code>immersive</code> modes.</td> </tr> </tbody> </table> ## Showing as a background ![](https://cdn.restlessdreams.cloud/0ad0cc02-5a74-453b-acaf-e340d4c25c0a.webp) ### Defining the Object The first thing we need to do is create our canvas object, we'll call this one `stars`. ```javascript monogatari.action ('Canvas').objects ({ stars: { } }); ``` We want two layers for it, one represents the sky and the other one is where the stars will be drawn, therefore, we'll provide these layers to our object: ```javascript monogatari.action ('Canvas').objects ({ stars: { layers: ['sky', 'stars'], } }); ``` Next, we'll define the functions used to draw both the sky and stars in the object's `props` property. We're placing them there because we'll want to re-draw the canvas when the window is resized so having them in a place that we can easily access from both the `start` and `resize` functions would be the best. ```javascript monogatari.action ('Canvas').objects ({ stars: { layers: ['sky', 'stars'], props: { drawStar: (ctx, r) => { ctx.save(); ctx.beginPath(); ctx.moveTo(r, 0); for (let i = 0; i < 9; i++) { ctx.rotate(Math.PI / 5); if (i % 2 === 0) { ctx.lineTo((r / 0.525731) 0.200811, 0); } else { ctx.lineTo(r, 0); } } ctx.closePath(); ctx.fill(); ctx.restore(); }, drawSky: (sky) => { const width = sky.width; const height = sky.height; const ctx = sky.getContext('2d'); ctx.fillRect(0, 0, width, height); ctx.translate(width / 2, height / 2); // Create a circular clipping path ctx.beginPath(); ctx.arc(0, 0, width * 0.4, 0, Math.PI * 2, true); ctx.clip(); // draw background const lingrad = ctx.createLinearGradient(0, -1 * width / 2, 0, height / 2); lingrad.addColorStop(0, '#232256'); lingrad.addColorStop(1, '#143778'); ctx.fillStyle = lingrad; ctx.fillRect(-width/2, -height/2, width, height); }, drawStars: (stars, drawStar) => { const width = stars.width; const height = stars.height; const ctx = stars.getContext('2d'); // draw stars for (var j = 1; j < 50; j++) { ctx.save(); ctx.fillStyle = '#fff'; ctx.translate(width - Math.floor(Math.random() * width), height - Math.floor(Math.random() * height)); drawStar(ctx, Math.floor(Math.random() * 4) + 2); ctx.restore(); } } }, } }); ``` We're now set to create our `start` function. On it we'll use the functions we added on the props property to actually draw our canvas. This time we didn't provided a `state` object because we don't have any variable that will be changing. ```javascript monogatari.action ('Canvas').objects ({ stars: { layers: ['sky', 'stars'], props: { drawStar: (ctx, r) => { ctx.save(); ctx.beginPath(); ctx.moveTo(r, 0); for (let i = 0; i < 9; i++) { ctx.rotate(Math.PI / 5); if (i % 2 === 0) { ctx.lineTo((r / 0.525731) * 0.200811, 0); } else { ctx.lineTo(r, 0); } } ctx.closePath(); ctx.fill(); ctx.restore(); }, drawSky: (sky) => { const width = sky.width; const height = sky.height; const ctx = sky.getContext('2d'); ctx.fillRect(0, 0, width, height); ctx.translate(width / 2, height / 2); // Create a circular clipping path ctx.beginPath(); ctx.arc(0, 0, width * 0.4, 0, Math.PI * 2, true); ctx.clip(); // draw background const lingrad = ctx.createLinearGradient(0, -1 * width / 2, 0, height / 2); lingrad.addColorStop(0, '#232256'); lingrad.addColorStop(1, '#143778'); ctx.fillStyle = lingrad; ctx.fillRect(-width/2, -height/2, width, height); }, drawStars: (stars, drawStar) => { const width = stars.width; const height = stars.height; const ctx = stars.getContext('2d'); // draw stars for (var j = 1; j < 50; j++) { ctx.save(); ctx.fillStyle = '#fff'; ctx.translate(width - Math.floor(Math.random() * width), height - Math.floor(Math.random() * height)); drawStar(ctx, Math.floor(Math.random() * 4) + 2); ctx.restore(); } } }, start: function ({ sky, stars }, props, state, container) { let width = 150; let height = 150; if (container.props.mode === 'background') { width = this.width (); height = this.height (); } sky.width = width; sky.height = height; stars.width = width; stars.height = height; props.drawSky (sky); props.drawStars (stars, props.drawStar); return Promise.resolve (); } }); ``` Next, we'll create our `stop` function. On canvas objects that feature animations this is a very important function since all animations need to be canceled. Otherwise, they will drain the memory of the browser even if they're no longer being shown. In this case, we don't have any animations but we'll clear the canvas object completely when stopped. ```javascript monogatari.action ('Canvas').objects ({ stars: { layers: ['sky', 'stars'], props: { drawStar: (ctx, r) => { ctx.save(); ctx.beginPath(); ctx.moveTo(r, 0); for (let i = 0; i < 9; i++) { ctx.rotate(Math.PI / 5); if (i % 2 === 0) { ctx.lineTo((r / 0.525731) * 0.200811, 0); } else { ctx.lineTo(r, 0); } } ctx.closePath(); ctx.fill(); ctx.restore(); }, drawSky: (sky) => { const width = sky.width; const height = sky.height; const ctx = sky.getContext('2d'); ctx.fillRect(0, 0, width, height); ctx.translate(width / 2, height / 2); // Create a circular clipping path ctx.beginPath(); ctx.arc(0, 0, width * 0.4, 0, Math.PI * 2, true); ctx.clip(); // draw background const lingrad = ctx.createLinearGradient(0, -1 * width / 2, 0, height / 2); lingrad.addColorStop(0, '#232256'); lingrad.addColorStop(1, '#143778'); ctx.fillStyle = lingrad; ctx.fillRect(-width/2, -height/2, width, height); }, drawStars: (stars, drawStar) => { const width = stars.width; const height = stars.height; const ctx = stars.getContext('2d'); // draw stars for (var j = 1; j < 50; j++) { ctx.save(); ctx.fillStyle = '#fff'; ctx.translate(width - Math.floor(Math.random() * width), height - Math.floor(Math.random() * height)); drawStar(ctx, Math.floor(Math.random() * 4) + 2); ctx.restore(); } } }, start: function ({ sky, stars }, props, state, container) { let width = 150; let height = 150; if (container.props.mode === 'background') { width = this.width (); height = this.height (); } sky.width = width; sky.height = height; stars.width = width; stars.height = height; props.drawSky (sky); props.drawStars (stars, props.drawStar); return Promise.resolve (); }, stop: ({ sky, stars }, props, state, container) => { sky.getContext('2d').clearRect (0, 0, sky.width, sky.height); stars.getContext('2d').clearRect (0, 0, stars.width, stars.height); } }); ``` Finally, since we mentioned we wanted to re-draw our canvas when the window got resized $to make it always fit the entire screen$, we'll create our `resize` function with code very similar to our `start` function. ```javascript monogatari.action ('Canvas').objects ({ stars: { layers: ['sky', 'stars'], props: { drawStar: (ctx, r) => { ctx.save(); ctx.beginPath(); ctx.moveTo(r, 0); for (let i = 0; i < 9; i++) { ctx.rotate(Math.PI / 5); if (i % 2 === 0) { ctx.lineTo((r / 0.525731) * 0.200811, 0); } else { ctx.lineTo(r, 0); } } ctx.closePath(); ctx.fill(); ctx.restore(); }, drawSky: (sky) => { const width = sky.width; const height = sky.height; const ctx = sky.getContext('2d'); ctx.fillRect(0, 0, width, height); ctx.translate(width / 2, height / 2); // Create a circular clipping path ctx.beginPath(); ctx.arc(0, 0, width * 0.4, 0, Math.PI * 2, true); ctx.clip(); // draw background const lingrad = ctx.createLinearGradient(0, -1 * width / 2, 0, height / 2); lingrad.addColorStop(0, '#232256'); lingrad.addColorStop(1, '#143778'); ctx.fillStyle = lingrad; ctx.fillRect(-width/2, -height/2, width, height); }, drawStars: (stars, drawStar) => { const width = stars.width; const height = stars.height; const ctx = stars.getContext('2d'); // draw stars for (var j = 1; j < 50; j++) { ctx.save(); ctx.fillStyle = '#fff'; ctx.translate(width - Math.floor(Math.random() * width), height - Math.floor(Math.random() * height)); drawStar(ctx, Math.floor(Math.random() * 4) + 2); ctx.restore(); } } }, start: function ({ sky, stars }, props, state, container) { let width = 150; let height = 150; if (container.props.mode === 'background') { width = this.width (); height = this.height (); } sky.width = width; sky.height = height; stars.width = width; stars.height = height; props.drawSky (sky); props.drawStars (stars, props.drawStar); return Promise.resolve (); }, stop: ({ sky, stars }, props, state, container) => { sky.getContext('2d').clearRect (0, 0, sky.width, sky.height); stars.getContext('2d').clearRect (0, 0, stars.width, stars.height); }, resize: function ({ sky, stars }, props, state, container) { if (container.props.mode === 'background') { const width = this.width (); const height = this.height (); sky.getContext('2d').clearRect (0, 0, sky.width, sky.height); stars.getContext('2d').clearRect (0, 0, stars.width, stars.height); sky.width = width; sky.height = height; stars.width = width; stars.height = height; props.drawSky (sky); props.drawStars (stars, props.drawStar); } } } }); ``` ### Using it in our script Once we've got our canvas object setup, we can go ahead and show it in our game. ```javascript monogatari.script ({ // The game starts here. 'Start': [ 'show canvas stars background with fadeIn', 'Shooting for the stars!', 'end' ] }); ``` --- # Preload > Preload assets to ensure smooth playback Source: https://monogatari.io/v2/script-actions/preload Section: Documentation ## Description ```text 'preload <type> <asset> [blocking]' 'preload character <id> <sprite> [blocking]' 'preload block <block_id> [blocking]' ``` The preload action allows you to load assets into memory before they are needed. This prevents lag or loading delays during gameplay, ensuring a smooth experience for the player. Action ID: `Preload` Reversible: No (Reverting does nothing) Requires User Interaction: No ## Parameters | Parameter | Description | | :--- | :--- | | `type` | The category of the asset (see [Supported Categories](#supported-categories) below). | | `asset` | The name/identifier of the asset to preload (as registered in `monogatari.assets()`). | | `id` | When preloading a character, the character's ID. | | `sprite` | When preloading a character, the sprite name (as defined in the character's `sprites` object). | | `block_id` | When using `preload block`, the ID of the defined preload block to load. | | `blocking` | (Optional) If included, the game will wait for the asset(s) to finish loading before proceeding to the next statement. | ## Supported Categories ### Default Audio Categories (use `audio` loader) - `music` - Background music tracks - `sounds` or `sound` - Sound effects - `voices` or `voice` - Voice clips ### Default Image Categories (use `image` loader) - `scenes` or `scene` - Scene backgrounds - `images` or `image` - General images - `characters` - Character sprites (uses special syntax, see examples) Note: Singular forms (`sound`, `voice`, `scene`, `image`) are aliases for their plural counterparts. ## Examples ### Preload a single music track ```javascript 'preload music theme_song' ``` ### Preload a scene (blocking) ```javascript 'preload scene library blocking' ``` ### Preload a sound effect ```javascript 'preload sound explosion blocking' ``` ### Preload a character sprite ```javascript 'preload character y happy blocking' ``` ### Preload a predefined block of assets ```javascript 'preload block Chapter1' ``` ## Preload Blocks Preload blocks allow you to group multiple assets together to be preloaded at once. These are defined using `monogatari.action('Preload').blocks()`. ### The `default` Block The `default` block is a special preload block that runs automatically during the game's initial loading screen. Assets defined in the `default` block are: - Decoded and cached - Audio is decoded to AudioBuffers, images are pre-decoded for immediate display - Loaded before gameplay - Players see the loading progress bar while these assets load - Ready for instant playback - No delay when first using these assets in-game ```javascript monogatari.action('Preload').blocks({ 'default': { music: ['main_theme', 'menu_music'], scenes: ['title_screen', 'chapter1_intro'], sounds: ['click', 'notification'], characters: { 'y': ['normal', 'happy', 'sad'] } } }); ``` > [!TIP] > Use the `default` block for assets needed immediately or frequently throughout the game. For chapter-specific assets, use named blocks and the `preload block` action. ### Default Block vs. Legacy Preloading | With `default` Block | Without `default` Block (Legacy) | | :--- | :--- | | Only specified assets are preloaded | ALL registered assets are preloaded | | Audio is decoded to AudioBuffers | Audio is only fetched to browser cache | | Images are pre-decoded | Images are only fetched to browser cache | | Faster first playback | May have slight delay on first use | | More control over initial load time | Longer initial load with many assets | ### Defining Named Blocks Named blocks are loaded on-demand using `preload block <name>` in your script: ```javascript monogatari.action('Preload').blocks({ 'default': { // Loaded automatically at game start music: ['main_theme'], scenes: ['intro'] }, 'Chapter1': { // Loaded when you use 'preload block Chapter1' music: ['theme_song', 'battle_music'], scenes: ['school_gate', 'classroom'], sounds: ['door_open', 'footsteps'], characters: { 'y': ['happy', 'sad', 'normal'] } }, 'Chapter2': { music: ['dramatic_theme'], scenes: ['rooftop'], images: ['sunset_photo'] } }); ``` ### Block Structure ```typescript interface PreloadBlock { music?: string[]; // Asset names from monogatari.assets('music', {...}) sounds?: string[]; // Asset names from monogatari.assets('sounds', {...}) voices?: string[]; // Asset names from monogatari.assets('voices', {...}) scenes?: string[]; // Asset names from monogatari.assets('scenes', {...}) images?: string[]; // Asset names from monogatari.assets('images', {...}) characters?: { // Character sprite names [characterId: string]: string[] // Sprite names from character's sprites object }; [customCategory: string]: string[] | undefined; // Custom categories (see below) } ``` ### Using Blocks in Scripts ```javascript monogatari.script({ 'Start': [ 'Before the chapter begins, let\'s load assets...', 'preload block Chapter1 blocking', 'All assets are now loaded!', // ... rest of chapter ] }); ``` ## Blocking vs Non-Blocking By default, preload is non-blocking - the game immediately advances to the next statement while assets load in the background. This is useful for preloading assets you'll need later. Adding the `blocking` keyword makes the action wait for the preload to complete before advancing. This is useful when you need the asset immediately after the preload statement. ```javascript // Non-blocking: loads in background while dialogue continues 'preload music boss_battle', 'The hero approaches the castle...', // Blocking: waits for asset to load before continuing 'preload scene castle_interior blocking', 'show scene castle_interior' ``` ## Advanced: Custom Categories You can register custom asset categories to use with the preload system. ### Registering a Custom Category ```javascript // Register a custom category 'posters' that uses the image loader monogatari.action('Preload').registerCategory('posters', 'image'); // Configure the assets path for your custom category const assetsPath = monogatari.setting('AssetsPath'); assetsPath.posters = 'images/posters'; monogatari.setting('AssetsPath', assetsPath); // Register assets for your custom category monogatari.assets('posters', { 'movie_poster': 'avengers.jpg', 'concert_poster': 'live_show.png' }); ``` ### Using Custom Categories Once registered, custom categories work like built-in ones: ```javascript // Single asset preload 'preload posters movie_poster blocking' // In preload blocks monogatari.action('Preload').blocks({ 'theater_scene': { posters: ['movie_poster', 'concert_poster'], music: ['theater_ambience'] } }); ``` ## Advanced: Custom Loaders For advanced use cases, you can register entirely custom loaders for new asset types. ### Registering a Custom Loader ```javascript monogatari.action('Preload').registerLoader('video', { loader: async (url, engine) => { // Custom loading logic const video = document.createElement('video'); video.src = url; await new Promise((resolve, reject) => { video.onloadeddata = resolve; video.onerror = reject; }); return video; }, cache: { get: (engine, key) => engine.videoCache?.(key), set: (engine, key, value) => engine.videoCache?.(key, value), delete: (engine, key) => engine.videoUncache?.(key), clear: (engine, prefix) => engine.videoClearCache?.(prefix) } }); // Then register categories to use this loader monogatari.action('Preload').registerCategory('videos', 'video'); ``` ## Related Actions - [Unload](/v2/script-actions/unload) - Release assets from memory when no longer needed --- # Play Voice > Play a voice audio file Source: https://monogatari.io/v2/script-actions/play-voice Section: Documentation ## Description ```javascript 'play voice <voice_id> [with [loop] [fade <time>] [volume <percentage>] [<effects>]]' 'play voice' // Resume all paused voices ``` The `play voice` action lets you play voice files so that you can make your characters speak. You can play as many voices as you want simultaneously. Important: Voice audio is automatically stopped when the player advances to the next statement. This ensures voice lines don't overlap with subsequent dialogue. To stop a voice manually, check out the [Stop Voice documentation](/v2/script-actions/stop-voice). Action ID: `Play` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | voice\_id | `string` | The name of the voice file you want to play. These assets must be declared beforehand. | | loop | `flag` | Optional. Makes the voice loop indefinitely. | | fade | `number` | Optional. Fade in time in seconds. | | volume | `number` | Optional. Volume percentage (0-100). | | effects | `various` | Optional. Audio effects to apply (see [Audio Effects](/v2/script-actions/play-music#audio-effects)). | ## Assets Declarations To play a voice, you must first add the file to your `assets/voices/` directory and then declare it. To do so, Monogatari has a function that will let you declare all kinds of assets for your game. ```javascript monogatari.assets('voices', { '<voice_id>': 'voiceFileName' }); ``` ### Supported Formats Each browser has its own format compatibility. MP3 however is the format supported by every browser. If you wish to use other formats, you can check a [compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility) to discover what browsers will be able to play it. ## Examples ### Play Voice The following will play the voice file, and once it ends, it will simply stop. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_001', 'This is the dialog that the voice file is narrating', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3' }); ``` ### Loop Voice The following will play the voice file, and once it ends, it will start over on an infinite loop until it is stopped using the [Stop Voice Action](/v2/script-actions/stop-voice). Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_001 with loop', 'This is the dialog that the voice file is narrating', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3' }); ``` ### Fade In Effect The following will play the voice file with a fade in effect. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_001 with fade 3', 'This is the dialog that the voice file is narrating', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3' }); ``` ### Custom Volume The following will set the volume of this voice to 73%. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_001 with volume 73', 'This is the dialog that the voice file is narrating', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3' }); ``` Please note that the user's preferences regarding volumes are always respected, which means this percentage is taken from the current player preferences. If the player has set the volume to 50%, the actual volume value for the voice will be: $$ 50\% \times 73\% = 36.5\% $$ ### Resume Paused Voices If voices have been paused using the [Pause action](/v2/script-actions/pause), you can resume them: ```javascript 'play voice' // Resume all paused voices ``` ### All Together You can combine all properties. The order doesn't matter. Script ```javascript monogatari.script({ 'Start': [ 'play voice dialog_001 with volume 100 loop fade 2', 'This is the dialog that the voice file is narrating', 'end' ] }); ``` Voice Assets ```javascript monogatari.assets('voices', { 'dialog_001': 'dialog_file_1.mp3' }); ``` ## Audio Effects Voice audio supports the same [audio effects system](/v2/script-actions/play-music#audio-effects) available for music, including filter, delay, compressor, tremolo, distortion, reverb, and many more. See the [Play Music documentation](/v2/script-actions/play-music#audio-effects) for a complete list of available effects and their usage. ### Example with Effects ```javascript 'play voice phone_call with filter highpass 300 1 filter lowpass 3000 1' ``` This simulates a phone call effect by filtering out low and high frequencies. ## Voice Behavior ### Auto-Stop on Proceed Voice players are automatically stopped when the player proceeds to the next statement. This prevents voice lines from overlapping. This behavior is controlled by the `shouldProceed` and `willProceed` lifecycle hooks in the Play action. ### Wait for Voice By default, if auto-proceed is enabled (not skip mode), the game will wait for voice playback to finish before automatically advancing. This ensures the player hears the full voice line. ## Related Actions - [Stop Voice](/v2/script-actions/stop-voice) - Stop playing voices - [Pause](/v2/script-actions/pause) - Pause playing media - [Play Music](/v2/script-actions/play-music) - Play background music (includes full audio effects documentation) --- # Play Sound > Play a sound effect Source: https://monogatari.io/v2/script-actions/play-sound Section: Documentation ## Description ```javascript 'play sound <sound_id> [with [loop] [fade <time>] [volume <percentage>] [<effects>]]' 'play sound' // Resume all paused sounds ``` The `play sound` action lets you play sound effects in your game. You can play as many sound effects as you want simultaneously. To stop the sound, check out the [Stop Sound documentation](/v2/script-actions/stop-sound). Action ID: `Play` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | sound\_id | `string` | The name of the sound you want to play. These assets must be declared beforehand. | | loop | `flag` | Optional. Makes the sound loop indefinitely. | | fade | `number` | Optional. Fade in time in seconds. | | volume | `number` | Optional. Volume percentage (0-100). | | effects | `various` | Optional. Audio effects to apply (see [Audio Effects](/v2/script-actions/play-music#audio-effects)). | ## Assets Declarations To play a sound, you must first add the file to your `assets/sounds/` directory and then declare it. To do so, Monogatari has a function that will let you declare all kinds of assets for your game. ```javascript monogatari.assets('sounds', { '<sound_id>': 'soundFileName' }); ``` ### Supported Formats Each browser has its own format compatibility. MP3 however is the format supported by every browser. If you wish to use other formats, you can check a [compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility) to discover what browsers will be able to play it. ## Examples ### Play Sound The following will play the sound, and once the sound ends, it will simply stop. Script ```javascript monogatari.script({ 'Start': [ 'play sound riverFlow', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'riverFlow': 'river_water_flowing.mp3' }); ``` ### Loop Sound The following will play the sound, and once the sound ends, it will start over on an infinite loop until it is stopped using the [Stop Sound Action](/v2/script-actions/stop-sound). Script ```javascript monogatari.script({ 'Start': [ 'play sound riverFlow with loop', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'riverFlow': 'river_water_flowing.mp3' }); ``` ### Fade In Effect The following will play the sound with a fade in effect. Script ```javascript monogatari.script({ 'Start': [ 'play sound riverFlow with fade 3', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'riverFlow': 'river_water_flowing.mp3' }); ``` ### Custom Volume The following will set the volume of this sound to 73%. Script ```javascript monogatari.script({ 'Start': [ 'play sound riverFlow with volume 73', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'riverFlow': 'river_water_flowing.mp3' }); ``` Please note that the user's preferences regarding volumes are always respected, which means this percentage is taken from the current player preferences. If the player has set the volume to 50%, the actual volume value for the sound will be: $$ 50\% \times 73\% = 36.5\% $$ ### Resume Paused Sounds If sounds have been paused using the [Pause action](/v2/script-actions/pause), you can resume them: ```javascript 'play sound' // Resume all paused sounds ``` ### All Together You can combine all properties. The order doesn't matter. Script ```javascript monogatari.script({ 'Start': [ 'play sound riverFlow with volume 100 loop fade 2', 'end' ] }); ``` Sound Assets ```javascript monogatari.assets('sounds', { 'riverFlow': 'river_water_flowing.mp3' }); ``` ## Audio Effects Sound effects support the same [audio effects system](/v2/script-actions/play-music#audio-effects) available for music, including filter, delay, compressor, tremolo, distortion, reverb, and many more. See the [Play Music documentation](/v2/script-actions/play-music#audio-effects) for a complete list of available effects and their usage. ### Example with Effects ```javascript 'play sound explosion with filter lowpass 800 2 convreverb 2 1.5' ``` This plays an explosion sound with a low-pass filter and reverb for a more distant, muffled effect. ## Related Actions - [Stop Sound](/v2/script-actions/stop-sound) - Stop playing sounds - [Pause](/v2/script-actions/pause) - Pause playing media - [Play Music](/v2/script-actions/play-music) - Play background music (includes full audio effects documentation) --- # Play Music > Play music media Source: https://monogatari.io/v2/script-actions/play-music Section: Documentation ## Description ```javascript 'play music <music_id> [with [loop] [fade <time>] [volume <percentage>] [<effects>]]' 'play music' // Resume all paused music ``` The `play music` action lets you play background music for your game. You can play as many songs as you want simultaneously. To stop the music, check out the [Stop Music documentation](/v2/script-actions/stop-music). Action ID: `Play` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | music\_id | `string` | The name of the music you want to play. These assets must be declared beforehand. | | loop | `flag` | Optional. Makes the music loop indefinitely. | | fade | `number` | Optional. Fade in time in seconds. | | volume | `number` | Optional. Volume percentage (0-100). | | effects | `various` | Optional. Audio effects to apply (see [Audio Effects](#audio-effects)). | ## Assets Declarations To play a song, you must first add the file to your `assets/music/` directory and then declare it. To do so, Monogatari has a function that will let you declare all kinds of assets for your game. ```javascript monogatari.assets('music', { '<music_id>': 'musicFileName' }); ``` ### Supported Formats Each browser has its own format compatibility. MP3 however is the format supported by every browser. If you wish to use other formats, you can check a [compatibility table](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility) to discover what browsers will be able to play it. ## Examples ### Play Music The following will play the song, and once the song ends, it will simply stop. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3' }); ``` ### Loop Music The following will play the song, and once the song ends, it will start over on an infinite loop until it is stopped using the [Stop Music Action](/v2/script-actions/stop-music). Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with loop', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3' }); ``` ### Fade In Effect The following will play the song with a fade in effect. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with fade 3', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3' }); ``` ### Custom Volume The following will set the volume of this song to 73%. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with volume 73', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3' }); ``` Please note that the user's preferences regarding volumes are always respected, which means this percentage is taken from the current player preferences. If the player has set the volume to 50%, the actual volume value for the song will be: $$ 50\% \times 73\% = 36.5\% $$ ### Resume Paused Music If music has been paused using the [Pause action](/v2/script-actions/pause), you can resume it: ```javascript 'play music' // Resume all paused music ``` ### All Together You can combine all properties. The order doesn't matter. Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with volume 100 loop fade 2', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3' }); ``` ## Audio Effects You can apply multiple audio effects to your music by specifying them in the properties. These effects use the Web Audio API for real-time audio processing. ### Effect Syntax Effects are specified by their name followed by their parameters: ```javascript 'play music <music_id> with <effect_name> <param1> <param2> ...' ``` ### Available Effects #### Filter Applies a Biquad filter (lowpass, highpass, etc.) Parameters: * `type` - Filter type: `lowpass`, `highpass`, `bandpass`, `notch`, `allpass`, `peaking`, `lowshelf`, `highshelf` (default: `lowpass`) * `frequency` - Cutoff frequency in Hz (default: `800`) * `Q` - Quality factor (default: `1`) * `gain` - Filter gain in dB (default: `0`) Example: ```javascript 'play music mainTheme with filter lowpass 400 2' ``` #### Delay A simple delay effect with feedback. Parameters: * `time` - Delay time in seconds (default: `0.4`) * `feedback` - Feedback amount 0-1 (default: `0.5`) * `mix` - Wet/dry mix 0-1 (default: `0.5`) Example: ```javascript 'play music mainTheme with delay 0.5 0.3 0.7' ``` #### Compressor Dynamic range compression. Parameters: * `threshold` - Compression threshold in dB (default: `-24`) * `knee` - Knee width in dB (default: `30`) * `ratio` - Compression ratio (default: `12`) * `attack` - Attack time in seconds (default: `0.003`) * `release` - Release time in seconds (default: `0.25`) Example: ```javascript 'play music mainTheme with compressor -20 20 8 0.01 0.1' ``` #### Tremolo Modulates the amplitude of the signal. Parameters: * `frequency` - Modulation frequency in Hz (default: `5`) * `depth` - Modulation depth 0-1 (default: `0.8`) Example: ```javascript 'play music mainTheme with tremolo 3 0.6' ``` #### Distortion Applies wave-shaping distortion. Parameters: * `amount` - Distortion amount (default: `50`) * `oversample` - Oversampling: `2x`, `4x`, or `none` (default: `4x`) Example: ```javascript 'play music mainTheme with distortion 30 2x' ``` #### Convolution Reverb Convolution reverb with a generated impulse response. Parameters: * `seconds` - Reverb duration in seconds (default: `2`) * `decay` - Decay rate (default: `2`) * `reverse` - Reverse the impulse response (default: `false`) Example: ```javascript 'play music mainTheme with convreverb 3 1.5' ``` #### Bitcrusher Reduces bit depth and sample rate of the signal. Parameters: * `bits` - Bit depth 1-16 (default: `4`) * `frequency` - Sample rate reduction 0-1 (default: `0.1`) Example: ```javascript 'play music mainTheme with bitcrusher 8 0.2' ``` #### AutoWah An envelope-following filter (auto-wah). Parameters: * `baseFrequency` - Base frequency in Hz (default: `100`) * `octaves` - Frequency range in octaves (default: `6`) * `sensitivity` - Envelope sensitivity 0-1 (default: `0.5`) * `Q` - Filter Q factor (default: `10`) Example: ```javascript 'play music mainTheme with autowah 200 4 0.7 15' ``` #### Panner Positions the sound in 3D space. Parameters: * `x` - X position (default: `0`) * `y` - Y position (default: `0`) * `z` - Z position (default: `0`) Example: ```javascript 'play music mainTheme with panner 1 0 0' ``` #### Phaser A sweeping phase-shifting effect. Parameters: * `frequency` - LFO frequency in Hz (default: `0.5`) * `depth` - Modulation depth in Hz (default: `1000`) * `feedback` - Feedback amount 0-1 (default: `0.5`) * `stages` - Number of filter stages (default: `4`) Example: ```javascript 'play music mainTheme with phaser 1 800 0.3 6' ``` #### Chorus Creates a thicker sound by modulating a delayed signal. Parameters: * `frequency` - LFO frequency in Hz (default: `1.5`) * `delay` - Delay time in seconds (default: `0.025`) * `depth` - Modulation depth in seconds (default: `0.002`) * `mix` - Wet/dry mix 0-1 (default: `0.5`) Example: ```javascript 'play music mainTheme with chorus 2 0.03 0.003 0.6' ``` #### Wah A sweeping filter effect, like a guitar wah-wah pedal. Parameters: * `baseFrequency` - Base frequency in Hz (default: `350`) * `Q` - Filter Q factor (default: `15`) * `depth` - Frequency sweep range in Hz (default: `1500`) * `frequency` - LFO frequency in Hz (default: `2`) Example: ```javascript 'play music mainTheme with wah 500 20 2000 1' ``` #### Ring Modulation Ring modulation for creating metallic, bell-like sounds. Parameters: * `frequency` - Modulator frequency in Hz (default: `30`) * `mix` - Wet/dry mix 0-1 (default: `0.5`) Example: ```javascript 'play music mainTheme with ringmod 50 0.7' ``` #### Saturator Soft clipping for warmth and harmonics. Parameters: * `drive` - Drive amount (default: `5`) Example: ```javascript 'play music mainTheme with saturator 3' ``` #### Limiter A hard compressor to prevent signal peaks from exceeding a threshold. Parameters: * `threshold` - Limiting threshold in dB (default: `-1.0`) * `release` - Release time in seconds (default: `0.05`) Example: ```javascript 'play music mainTheme with limiter -3 0.1' ``` #### Fade In Gradually increases the volume from silence to full over a duration. Parameters: * `duration` - Fade-in time in seconds (default: `1.0`) Example: ```javascript 'play music mainTheme with fadein 3' ``` #### Fade Out Gradually decreases the volume to silence over a duration. Parameters: * `duration` - Fade-out time in seconds (default: `1.0`) Example: ```javascript 'play music mainTheme with fadeout 3' ``` > [!NOTE] > `fadein` does the same thing as the `fade <time>` parameter shown near the top of this > page — both fade the music in. Use `fade <time>` for a quick fade-in; reach for the > `fadein` / `fadeout` effects when you want to chain fading together with other effects. ### Multiple Effects You can combine multiple effects on a single music track: ```javascript 'play music mainTheme with filter lowpass 600 1.5 delay 0.3 0.4 0.6 tremolo 4 0.5' ``` ### Effect Compatibility Some effects require AudioWorklet support, which may not be available in all browsers: * Bitcrusher and AutoWah require AudioWorklet support * If AudioWorklet is not available, these effects will fall back to a simple gain node (no effect) * Other effects use standard Web Audio API nodes and work in all modern browsers ### Example: Complex Audio Setup Script ```javascript monogatari.script({ 'Start': [ 'play music mainTheme with volume 80 loop filter lowpass 400 2 delay 0.5 0.3 0.4', 'play music ambient with volume 30 filter highpass 200 1 convreverb 4 1.5', 'Listen to all the effects!', 'end' ] }); ``` Music Assets ```javascript monogatari.assets('music', { 'mainTheme': 'mainThemeSong.mp3', 'ambient': 'ambientMusic.mp3' }); ``` This example creates a layered audio experience with: * A main theme with low-pass filtering, delay, and looping * An ambient track with high-pass filtering and reverb ## Related Actions - [Stop Music](/v2/script-actions/stop-music) - Stop playing music - [Pause](/v2/script-actions/pause) - Pause playing media --- # Placeholder Source: https://monogatari.io/v2/script-actions/placeholder Section: Documentation ## Description ```javascript '$ <placeholder_name>' ``` A placeholder allows you to save some action to use within your game by placing a placeholder on your script wherever you want to call it. This is particularly useful when you have an action that is repeated multiple times in your game or when loading your script from an external source. Action ID: `Placeholder` Reversible: Depends on the action provided Requires User Interaction: Depends on the action provided ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | `placeholder_name` | `string` | The name with which you saved the action you want to call. | ## Action Declarations To declare an action placeholder, you need to provide a name for it and a value. The value can be any valid monogatari action. ```javascript monogatari.$ ('menu', {"Choice":{ "Text": "Let's see, what do you want to know about?", "Animations":{ "Text": "Animations", "Do": "jump Animations" }, "Media":{ "Text": "Multimedia", "Do": "jump Media" }, "Scripting":{ "Text": "Scripting", "Do": "jump Script" }, "Playing":{ "Text": "Playing", "Do": "jump Playing" }, "Nothing": { "Text": "Nothing", "Do": "jump Nothing", "Condition": function () { return storage.playing && storage.media && storage.scripting && storage.animations; } } }}); ``` ## Examples ### Using a Choice in multiple places The following will declare the placeholder shown above, featuring a choice action. The recommended place to declare all your placeholders is your main.js file. ```javascript monogatari.$ ('menu', {"Choice":{ "Text": "Let's see, what do you want to know about?", "Animations":{ "Text": "Animations", "Do": "jump Animations" }, "Media":{ "Text": "Multimedia", "Do": "jump Media" }, "Scripting":{ "Text": "Scripting", "Do": "jump Script" }, "Playing":{ "Text": "Playing", "Do": "jump Playing" }, "Nothing": { "Text": "Nothing", "Do": "jump Nothing", "Condition": function () { return monogatari.storage ('someFlag'); } } }}); ``` And then, whenever you want to use that in your script, you just need to place the following statement, saving a lot of space and making it easier to have the same choice in multiple places: ```javascript '$ menu' ``` ### Dynamic Action Generation Another great way of using placeholders is generating actions dynamically. To make this happen, be sure that the name you use for your placeholders starts with `_` The value for your placeholder should be a function that can return any action. Your function will be evaluated before executing it to retrieve the action to run. > [!WARNING] > Beware, this is only recommended for advanced users. When using dynamic action generation, you will be responsible on providing the way to rollback what you did, this means you'll need to save up your own markers in order to know what action you executed before. ```javascript monogatari.$ ('_dialog', function () { // Within this function, `this` refers to the Monogatari object. if (this.storage ().someFlag) { return 'y This means the flag was true!'; } else { return 'y This means the flag was false!'; } }); ``` ### Passing Arguments into Placeholders Arguments can be used in Placeholders like so: ```javascript monogatari.$ ('_myAction', (arg1, arg2) => { return `${arg1} ${arg2}`; }); ``` Which would be called like this: ```javascript '$ _myAction something something' ``` Placeholders can also have argument passed into them for dynamic functions. The following is an example of a placeholder action that yields a returnable function object block that adds a string argument to an array. ```javascript monogatari.$ ('_addToInventory', (myArgument) => ({'Function':{ 'Apply': function(){ monogatari.storage().inventory.unshift(myArgument); }, 'Revert':function(){ monogatari.storage().inventory.shift(); } }})); ``` We'll declare our `inventory` as an array in `storage.js` ```javascript monogatari.storage ({ inventory: ["Sword"], }); ``` And then in our script, we'd call the placeholder like this! ```javascript monogatari.script ({ 'Start': [ "That's a cool potion. Let's pick it up and put it into our inventory.", "$ _addToInventory Potion", "Now I am holding a {{inventory.0}}", ] }); ``` Please note that placeholder arguments are delimited by spaces, so if you want to use spaces in the passed argument strings, you'll need to get a little creative. There are plenty of ways around this. One easy way is to use ` ` instead of spaces. ```javascript monogatari.script ({ 'Start': [ "That's a cool potion. Let's pick it up and put it into our inventory.", "$ _addToInventory Potion of Strength.", "Now I am holding a {{inventory.0}}", ] }); ``` Another way to do this would be to capture all arguments and concatenate them into one string, then process that string. Up to you how you want to work with this feature! ## Related Actions - [Functions](/v2/script-actions/javascript) - Run JavaScript functions in your script - [Choices](/v2/script-actions/choices) - Present options to players --- # Pause > Pause playing media Source: https://monogatari.io/v2/script-actions/pause Section: Documentation ## Description ```javascript 'pause <type> [media_id]' ``` The pause action allows you to pause currently playing media. This is useful for temporarily stopping music, sounds, or voices that you want to resume later. Action ID: `Pause` Reversible: Yes (resumes the paused media on revert) Requires User Interaction: No ## Parameters | Parameter | Description | | :--- | :--- | | `type` | The type of media to pause: `music`, `sound`, or `voice`. | | `media_id` | (Optional) The specific asset name to pause. If omitted, all media of the specified type will be paused. | ## Examples ### Pause All Music ```javascript 'pause music' ``` ### Pause a Specific Music Track ```javascript 'pause music mainTheme' ``` ### Pause All Sounds ```javascript 'pause sound' ``` ### Pause a Specific Sound ```javascript 'pause sound explosion' ``` ### Pause All Voices ```javascript 'pause voice' ``` ### Pause a Specific Voice ```javascript 'pause voice dialog_001' ``` ## Resuming Paused Media To resume paused media, use the corresponding play action without specifying a new asset: ```javascript 'pause music', // Pause all music 'Some dialogue here...', 'play music', // Resume all paused music 'pause sound fireCracks', // Pause specific sound 'Something happens...', 'play sound', // Resume all paused sounds (including fireCracks) ``` Note: When resuming with `play <type>`, ALL paused media of that type will resume. The play action with a media ID will start new playback, not resume the paused instance. ## Pause vs Stop | Action | Effect | Reversible | Can Resume | | :--- | :--- | :--- | :--- | | Pause | Temporarily stops playback, preserving position | Yes (resumes) | Yes, with `play <type>` | | Stop | Completely stops and removes the player | Yes (restarts from history) | No, must replay from start | Use pause when you want to temporarily stop media and resume from where it left off. Use stop when you're done with the media entirely. ## Use Cases ### Scene Transition ```javascript monogatari.script({ 'Start': [ 'play music peaceful with loop', 'The village was quiet...', 'pause music', 'Suddenly, a loud crash!', 'play sound crash', 'play music', // Resume peaceful music 'The villagers looked around nervously.', 'end' ] }); ``` ### Dramatic Pause ```javascript monogatari.script({ 'Start': [ 'play music suspense with loop', 'play sound heartbeat with loop', 'The tension was unbearable...', 'pause music', 'pause sound', '...', 'play music', 'play sound', 'And then it happened!', 'end' ] }); ``` ## Related Actions - [Play Music](/v2/script-actions/play-music) - Play background music - [Play Sound](/v2/script-actions/play-sound) - Play sound effects - [Play Voice](/v2/script-actions/play-voice) - Play voice audio - [Stop Music](/v2/script-actions/stop-music) - Stop music completely - [Stop Sound](/v2/script-actions/stop-sound) - Stop sounds completely - [Stop Voice](/v2/script-actions/stop-voice) - Stop voices completely --- # Next > Continue to the next statement on the script Source: https://monogatari.io/v2/script-actions/next Section: Documentation ## Description ```javascript 'next' ``` The `next` action will simply continue to the next statement on the script without doing anything else. This action is meant to be used in the `Do` property of [`Choices`](/v2/script-actions/choices) to simply carry on with the script or, as fillers to fill up a space left by a deleted statement in an already-released game. Action ID: Next Reversible: Yes Requires User Interaction: No --- # Jump > Jump to a different label in your script Source: https://monogatari.io/v2/script-actions/jump Section: Documentation ## Description ```text 'jump <label_id>' ``` The `jump` action moves script execution to a different label. This is essential for creating branching narratives, chapters, and non-linear story structures. Action ID: `Jump` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `label_id` | `string` | No | The name of the label to jump to. | ## Behavior When a `jump` action is executed: 1. Validates that the target label exists 2. Stops any ambient audio 3. Records the jump in history (source and destination) 4. Changes the current label and resets step to 0 5. Clears the dialog (unless in NVL mode) 6. Executes the first statement of the new label ## Basic Usage ```javascript monogatari.script({ 'Start': [ 'y Hello! Let me take you to Chapter 1.', 'jump Chapter1' ], 'Chapter1': [ 'show scene forest', 'y Welcome to Chapter 1!', 'end' ] }); ``` ## Branching with Choices The `jump` action is commonly used with choices to create branching paths: ```javascript monogatari.script({ 'Start': [ 'y Where do you want to go?', {'Choice': { 'Forest': { 'Text': 'Go to the forest', 'Do': 'jump Forest' }, 'Beach': { 'Text': 'Go to the beach', 'Do': 'jump Beach' }, 'Mountain': { 'Text': 'Go to the mountain', 'Do': 'jump Mountain' } }} ], 'Forest': [ 'show scene forest', 'y The forest is peaceful.', 'end' ], 'Beach': [ 'show scene beach', 'y The ocean breeze is refreshing!', 'end' ], 'Mountain': [ 'show scene mountain', 'y The view from up here is amazing!', 'end' ] }); ``` ## Organizing Large Scripts Use labels to organize your script into logical sections: ```javascript monogatari.script({ // Story start 'Start': [ 'show scene title_screen', 'wait 2000', 'jump Prologue' ], // Prologue 'Prologue': [ 'show scene city_night', 'y It all started on a rainy night...', 'jump Chapter1' ], // Chapter 1 'Chapter1': [ 'show scene apartment', 'y Chapter 1: A New Beginning', // Chapter content... 'jump Chapter2' ], // Chapter 2 'Chapter2': [ 'show scene school', 'y Chapter 2: First Day', // Chapter content... 'end' ] }); ``` ## HTML Data Attribute You can trigger jumps from HTML elements using the `data-jump` attribute: ```html <button data-action="jump" data-jump="SpecialScene">Go to Special Scene</button> ``` When clicked, this will execute `jump SpecialScene`. ## Error Handling If the target label doesn't exist, the engine will display an error showing: - The target label that wasn't found - All available labels in your script - The current location in your script ```javascript // This will show an error if 'NonExistent' label doesn't exist 'jump NonExistent' ``` ## Rollback Behavior The `jump` action records history to support the back button: - Pressing back after a jump returns to the source label and step - The jump history tracks both source and destination - Label history is also maintained for proper rollback > [!NOTE] > While jump is technically reversible, complex jump sequences may have unexpected rollback behavior. Test your back button functionality when using multiple jumps. ## Examples ### Conditional Jumps with Functions ```javascript monogatari.script({ 'Start': [ function() { const affection = monogatari.storage().game.affection; if (affection >= 50) { return 'jump GoodRoute'; } else { return 'jump NormalRoute'; } } ], 'GoodRoute': [ 'y You\'ve been so kind to me!', 'end' ], 'NormalRoute': [ 'y It was nice meeting you.', 'end' ] }); ``` ### Loop Back Pattern ```javascript monogatari.script({ 'Start': [ 'jump DailyLoop' ], 'DailyLoop': [ 'y Another day begins...', 'y What should I do today?', {'Choice': { 'Study': { 'Text': 'Study', 'Do': 'jump Study' }, 'Rest': { 'Text': 'Rest', 'Do': 'jump Rest' } }} ], 'Study': [ 'y I studied hard today.', function() { monogatari.storage().game.studyCount++; return true; }, 'jump CheckProgress' ], 'Rest': [ 'y I took a relaxing break.', 'jump DailyLoop' // Loop back ], 'CheckProgress': [ function() { if (monogatari.storage().game.studyCount >= 3) { return 'jump Graduation'; } return 'jump DailyLoop'; // Loop back } ], 'Graduation': [ 'y I graduated!', 'end' ] }); ``` ## Related Actions - [End](/v2/script-actions/end) - End the game - [Wait](/v2/script-actions/wait) - Pause execution - [Clear](/v2/script-actions/clear) - Clear the text box - [Choices](/v2/script-actions/choices) - Present choices to the player --- # Functions > Run JavaScript functions in your script Source: https://monogatari.io/v2/script-actions/javascript Section: Documentation ## Description Even though you can put more JavaScript code in the `main.js` file and do a lot of things there, sometimes we want to do something in some part of our game. This is why you can also put some JavaScript inside your game's script. Action ID: `Function` Reversible: Yes Requires User Interaction: No ## Reversible Functions So far, we've been using normal JavaScript functions to achieve more functionality but one problem was that this functions were not reversible, meaning that the players were not able to go back over a function. Let's see what we mean by that, let's say you are building some kind of RPG elements in your game and thus your player has stats. Normally, those stats would be declared inside your storage variable like this: ```javascript 'use strict'; // Persistent Storage Variable monogatari.storage ({ player: { intelligence: 0, ability: 0, strength: 0 } }); ``` Now, inside your script you would probably make some modifications of those stats depending on what the user does or how the story goes. ```javascript monogatari.script({ // The game starts here. 'Start': [ 'h Currently you have {{player.intelligence}} points of Intelligence but you seem far more intelligent, how about we add five points?', function () { this.storage ('player', { intelligence: this.storage ('player').intelligence + 5 }); return true; }, 'h There you have it, you now have {{player.intelligence}} points of Intelligence', 'end' ] }); ``` So, if we played this game, the first text would appear, then after we click for the next one, the function would be run adding 5 points to our intelligence stat and immediately would show the next text. If we wanted to go back to the first text it wouldn't be possible. This is mainly due to Monogatari not knowing what you are doing exactly in your function, if it were to allow you to go back, we could be getting infinite points just by going back and playing it again because there is no way to know what changed. To solve this problem and allow users to go back, Monoagatari v1.4 introduced reversible 'Function' objects, as with all the special script objects, these are defined in a JSON format, let's take a look at how the same situation as above would look like: ```javascript monogatari.script({ // The game starts here. 'Start': [ 'h Currently you have {{player.intelligence}} points of Intelligence but you seem far more intelligent, how about we add five points?', {'Function':{ 'Apply': function () { this.storage ('player', { intelligence: this.storage ('player').intelligence + 5 }); return true; }, 'Revert': function () { this.storage ('player', { intelligence: this.storage ('player').intelligence - 5 }); } }}, 'h There you have it, you now have {{player.intelligence}} points of Intelligence', 'end' ] }); ``` As you can see, we replaced the function with a `'Function'` object which has 2 properties, an `'Apply'` function which will run when going over the game and the `'Revert'` function which will be run when going back. This now solves the previous problem we had since we are using `'Apply'` to add the 5 points and `'Revert'` to subtract them in case the player went back and thus makes possible for players to go back even when a function was run. Just as with common functions, you can use Promises and also control the flow of the game by returning `true` or `false` in the `'Apply'` function. > [!NOTE] > For backwards compatibility, `'Reverse'` is still supported as an alias for `'Revert'`, but using `'Revert'` is recommended for consistency with other Monogatari actions. ## Normal Functions > [!WARNING] > Using normal JavaScript functions is not recommended because they can't be reverted and thus, players can't roll back their game on parts where functions are present which gives the impression that it's an error on the game rather than it being planned. To do it, you can actually using JavaScript functions. Yes, just like you would on any other JS file, you can use function syntax inside your script. To control the flow of your game, you can make the function return either true $Will immediately execute the next statement.$ or false $Will wait until the user clicks again.$ if it does not return one of those two, it will wait by default. Example: ```javascript 'Hi there!', function () { alert('This is pretty useful!'); return true; // Will make the engine execute the next statement when the function finishes. }, 'Isn’t it?' ``` While that may be ok for a few functions, as you can see after a while your code starts to become more complicated, a way to simplify things is declaring the functions before your script and then just using the name to call it in the script like this: ```javascript function sendAlert () { alert('This is pretty useful!'); return true; } Monogatari.script ({ // The game starts here. 'Start': [ 'Hello, after this the function will be run.', sendAlert, // You can use just the name of the function! 'Well, that looks a lot better!' ] }); ``` Using that technique will make your game a lot more easy to debug and update! ## Async Functions While the advanced way adds a lot of more possibilities to your game, it still doesn't solve the fact that you may need to realize some async tasks such as a request or other activities. Since v1.3.2, using [JavaScript Promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) is possible. ```javascript function asyncFunction () { return new Promise ((resolve, reject) => { // All your code should be here setTimeout (function (){ // You need to resolve the promise once your task is done resolve ('Success!'); }, 2150); }).then ((successMessage) => { alert (successMessage); return true; }); } Monogatari.script ({ // The game starts here. 'Start': [ 'Hello, after this the function will be run.', asyncFunction, 'Well, that looks a lot better!' ] }); ``` Just as with the common functions, if you return a true value from your promise, the next statement will be executed as soon as it's done and will wait if you return anything else. The game will also block on the meantime so the player won't be able to continue until the Promise is resolved. --- # Input > Displays an input dialog to the player Source: https://monogatari.io/v2/script-actions/input Section: Documentation ## Description There are many cases where we need input from the user, like when you want to know their name. The Input statement is represented in your Script as an Object and it allows you to define the text to show to your players, the type of input, the default value, validations, etc. Action ID: `Input` Reversible: Yes, as long as a [`Revert` function](/v2/script-actions/input#input-revert) is implemented. Requires User Interaction: Yes ## Properties | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `Text` | `string` | No | The text to be displayed in the input dialog. Supports storage and translation interpolations. | | `Type` | `string` | Yes | Default is `text`. The kind of input: `text`, `number`, `password`, `email`, `color`, `select`, `radio`, `checkbox` | | `Default` | `string` | Yes | The default value for the input. Supports storage and translation interpolations. | | `Options` | `Array<object>` | Yes | Options for `select`, `radio`, or `checkbox` types. Each option has `label` and `value` properties. | | `Validation` | `function` | Yes | Function returning boolean. Validates the input before saving. | | `Save` | `function` | Yes | Function that receives the validated input. Typically saves to storage. | | `Revert` | `function` | Yes | Function to undo the Save action when rolling back. Required for rollback support. | | `Warning` | `string` | Yes | Message shown when validation fails. Supports interpolations. | | `actionString` | `string` | Yes | Default is `'OK'`. Translation key for the submit button text. | | `Class` | `string` | Yes | Space-separated CSS class names for styling. | | `Timer` | `object` | Yes | Timer configuration with `time` (ms) and `callback` properties. | | `Attributes` | `object` | Yes | HTML attributes to add to the input element (e.g., `placeholder`, `maxlength`). | ## Input Text The `Text` property specifies the text that will appear to the player in the input dialog. This is the only property that is required. ## Input Validation The `Validation` property expects a function. When the player presses the submit button in your input dialog, the value they provided will be passed to your `Validation` function. In there, you can perform any validation you need depending on your game's context and what was the purpose of your input. The function should return a boolean value $`true` or `false`$ to indicate if the value was valid or not. If your validation has to perform some asynchronous operations such as consulting with an external server, then you can also return a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to the boolean value. If the validation fails, the [input's warning](/v2/script-actions/input#input-warning) will be shown to the player. ### Synchronous Validation Let's take a look at the following input, by default an input that doesn't specifies a `Type` property has the `text` type so it expects the player to type something into a text field: ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }}, ``` As you can see, we have provided a simple validation function there: ```javascript (input) => { return input.trim ().length > 0; } ``` This function is receiving the player's `input` and then, checks if that input is valid by checking if it has a length greater than 0 or, in simpler words, whether it received a non-empty input which could happen if the player didn't type anything and just pressed the submit button. By returning the result of that validation, it will return `true` when the input is not empty and `false` when the input is empty. Our code doesn't deal with any [asynchronous function](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous) so we can just return a boolean value this time. ### Asynchronous Validation There may come a time when for some reason, you want some complex validation to be perform on an input's value. For example, when you have to check with a server to determine whether it's valid or not. Let's say we have a server setup that given a name, it will returns us an object like this one based on some requirements we have, for example whether it's a full name $name and last name$ or not. ```javascript { valid: true } // When the name is valid { valid: false } // When the name is not valid ``` Now, checking with our server is not an operation that we can know how much it'll take to finish so, we want to wait for it to return us the result and only then, we can determine in our game if it was actually valid or not. Here's a sample code on how we could achieve that: ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { if (input.trim ().length === 0) { return false; } return fetch (`https://myserver.com/api/validate?name=${input}`) .then ((response) => { return response.json (); }).then (({ valid }) => { return Promise.resolve (valid); }); }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }}, ``` Let's pay closer attention to our validation function this time: ```javascript (input) => { if (input.trim ().length === 0) { return false; } return fetch (`https://myserver.com/api/validate?name=${input}`) .then ((response) => { return response.json (); }).then (({ valid }) => { return Promise.resolve (valid); }); } ``` As you can see, we first did a simple check to determine if the input wasn't empty $`length 0`$ because if it was, we can tell right away it wasn't a valid name and there's no need to check with our server so we make an early `return` if that's the case. If the input was not empty, we perform the call to our server which should return us the object we discussed before letting us know if the name was valid or not. Once we receive that object, we can finally tell our validation function to return that `Promise.resolve (valid)` value which in the end, contains the valid property returned to us by the server. ## Input Warning The `Warning` property expects a `string` value that will be shown to the player if the validation function determines the input was invalid. Keeping the name example from before, this input will validate the value provided by checking if it wasn't empty: ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }} ``` If the player provided an empty value $thus causing the validation function to deem it invalid$, the text in the `Warning` property will be shown to the player so they know something was wrong with the info they provided and try again: ![](https://cdn.restlessdreams.cloud/c48cda80-2d88-486e-9342-8feaaebed6e5.webp) ## Input Save Once the `Validation` function is run and it determines the input was valid, the value will be passed along to the `Save` function. Inputs were created mostly to get information out of the player so the `Save` function is where you would, as it name says, save that information or perform any other action you need to do now that you know what the player provided is valid. Normally this operation would involve some variable in your game's storage: ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { if (input.trim ().length === 0) { return false; } return fetch (`https://myserver.com/api/validate?name=${input}`) .then ((response) => { return response.json (); }).then (({ valid }) => { return Promise.resolve (valid); }); }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }}, ``` If we take a closer look to the `Save` function, we can see it's saving the player's input in the player.name property on the storage: ```javascript (input) => { monogatari.storage ({ player: { name: input }}); } ``` ### Changing the game flow Something really important to know about this function is that the value it returns will affect the flow of the game. If the value returns `void` $nothing like the one above$ or `true`, the game will continue to the next statement on the script as soon as the save operation finishes. If it returns `false`, then the input dialog will disappear but the player will have to click once more for the game to carry on. Just like the [Validation function](/v2/script-actions/input#input-validation), this one is also able to perform asynchronous operations and the flow will be affected by what the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) it returns resolves to. ## Input Revert You probably want players to be able to go back and enter a different value or simply go back to any point of the script even if that means passing through a previously answered input statement. In order to do so, you need to provide a `Revert` function. This function should be implemented by you and should do everything that's needed to revert what you did in your `Save` function. Let's take the following input as an example: ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }} ``` In the `Save` function, we're saving the player's name to the storage: ```javascript 'Save': (input) => { monogatari.storage ({ player: { name: input }}); } ``` Therefore, what we need to do in our `Revert` function is return that value in the storage to its original or default value: ```javascript 'Revert': () => { monogatari.storage ({ player: { name: '' }}); } ``` That way, whenever the player rolls back an input, the state of your game gets reset to what it was before. If you do not provide a `Revert` function however, players won't be able to go back when reaching an input statement, you can of course use this fact to your advantage if that's the behaviour you want, otherwise we always recommend implementing your `Revert`function so players can have the best experience possible. > [!WARNING] > Unlike most actions, the Input action has no default rollback. If you don't provide a `Revert` function, the action cannot be reverted and the player will be unable to roll back past it. ## Input Styling While you can always modify the overall style of your input dialogs by adding your own css code, some times you might want to have different styles for specific inputs in your game. As with most of the things in Monogatari, doing this involves using CSS classes. In your input object, you can provide a `Class` property. This property expects a `string` with space separated class names that will be added to your input dialog when it gets shown. First, let's remind this is what a un-styled input dialog looks like: ![](https://cdn.restlessdreams.cloud/307b2987-4511-4a83-8b15-8406caec8303.webp) Now, if we wanted to style it by adding some CSS classes that we have in our `main.css` file such as these ones: ```javascript .myInput .modal__content { background: #222; color: #fff; width: 100%; } .someClass { font-size: 2em; } .otherClass { background: rgba(0,184,212, 0.5); } ``` Then, all we'd have to do is add the `Class` property to our input and list those class names right there: ```javascript {'Input': { 'Class': 'myInput someClass otherClass', 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }}, ``` This will result in a stylized input dialog such as this one: ![](https://cdn.restlessdreams.cloud/fecedb3e-b6d9-452b-8b8b-36a7b0faf360.webp) ## Input Timer ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' 'Timer': { // Time in milliseconds time: 5000, // The function to run when the time is over callback: () => { // Get all choices being shown and that are not disabled const input = monogatari.element ().find ('text-input').get (0); input.content ('field').value ('My Name'); // // Pick one of those options randomly const submit = input.element ().find ('button').get (0); // // Fake a click on it submit.click (); // Promise friendly! return Promise.resolve (); } }, }}, ``` ## Input Types ### Text ![](https://cdn.restlessdreams.cloud/307b2987-4511-4a83-8b15-8406caec8303.webp) A `text` input allows the player to enter any kind of text, that includes numbers, symbols and even emojis. If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty string $`''`$ as the player's input. #### Sample Code ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }} ``` ### Number ![](https://cdn.restlessdreams.cloud/c5c298f9-a2ad-42d2-8d44-467d32778201.webp) A number input allows the player to enter any kind of numeric value. Note however that the `input` received in the `Validation` and `Save` functions will be a string so it has to be parsed to a number. If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty string $`''`$ as the player's input. #### Sample Code ```javascript {'Input': { 'Text': 'Enter your age', 'Type': 'number', 'Validation': (input) => { // Check if the input wasn't empty if (input.trim ().length === 0) { return false; } // Transform the input string to an integer number const age = parseInt (input); return age > 18; }, 'Save': (input) => { monogatari.storage ({ player: { age: parseInt (input) }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must be at least 18 years old to continue.' }} ``` ### Password ![](https://cdn.restlessdreams.cloud/68bec12f-6bec-460b-a84f-5eac41c07872.webp) A `password` will allow the player to enter any text just like the `text` input but whatever they type will be obscured with a symbol such as the asterisk $``$ or a dot $`•`$. If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty string $`''`$ as the player's input. #### Sample Code ```javascript {'Input': { 'Text': 'Enter the secret code', 'Type': 'password', 'Validation': (input) => { // Check what the player entered against our code return input.trim () === 'SecretC0de'; }, 'Save': (input) => { // Do something here, might not be necessary to // save anything for password inputs. }, 'Revert': () => { // Revert what we did in the save function }, 'Warning': 'That\'s not the right code.' }} ``` ### Select ![](https://cdn.restlessdreams.cloud/9ec7ea2b-51ce-4747-955a-6897025eff7c.webp) A `select` input allows you to provide different possible values for the player to choose from, they however will only be able to choose one of them. If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty string $`''`$ as the player's input. #### Sample Code ```javascript {'Input': { 'Text': 'What\'s your favorite color?', 'Type': 'select', 'Options': [ { label: 'Pink', value: 'pink', }, { label: 'Red', value: 'red', }, { label: 'Orange', value: 'orange', }, { label: 'Blue', value: 'blue', }, { label: 'Yellow', value: 'yellow', }, { label: 'Green', value: 'green', } ], 'Validation': (input) => { // We'll receive the 'value' property of the option // the player selected. return input.trim ().length > 0; }, 'Save': (input) => { // Save the favorite color in the storage monogatari.storage ({ player: { favorite_color: input }}); }, 'Revert': () => { // Reset the favorite color property monogatari.storage ({ player: { favorite_color: '' }}); }, 'Warning': 'You must select a color.' }} ``` ### Radio ![](https://cdn.restlessdreams.cloud/cb1e5a67-1163-4d53-a0d8-956dcf99e78f.webp) A `radio` input, just like the `select` input allows you to provide different possible values for the player to choose from and only allows them to choose one. If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty string $`''`$ as the player's input. ```javascript {'Input': { 'Text': 'What\'s your favorite color?', 'Type': 'radio', 'Options': [ { label: 'Pink', value: 'pink', }, { label: 'Red', value: 'red', }, { label: 'Orange', value: 'orange', }, { label: 'Blue', value: 'blue', }, { label: 'Yellow', value: 'yellow', }, { label: 'Green', value: 'green', } ], 'Validation': (input) => { // We'll receive the 'value' property of the option // the player selected. return input.trim ().length > 0; }, 'Save': (input) => { // Save the favorite color in the storage monogatari.storage ({ player: { favorite_color: input }}); }, 'Revert': () => { // Reset the favorite color property monogatari.storage ({ player: { favorite_color: '' }}); }, 'Warning': 'You must select a color.' }} ``` ### Checkbox ![](https://cdn.restlessdreams.cloud/4a1934d1-205d-42ff-9bc1-bda237ca7eca.webp) A `checkbox` also allows you to provide different possible values for the player to choose from but, contrary to the `radio` or `select` inputs, players will be able to choose more than one option. Since this input allows multiple choices to be chosen, the input argument received by the `Validation` and `Save` functions will be an array of strings instead of a string, for example: ```javascript ['pink', 'yellow'] ``` If the player doesn't enter any value, the `Validation` and `Save` functions will receive an empty array $`[]`$ as the player's input. #### Sample Code ```javascript {'Input': { 'Text': 'What are your favorite colors?', 'Type': 'checkbox', 'Options': [ { label: 'Pink', value: 'pink', }, { label: 'Red', value: 'red', }, { label: 'Orange', value: 'orange', }, { label: 'Blue', value: 'blue', }, { label: 'Yellow', value: 'yellow', }, { label: 'Green', value: 'green', } ], 'Validation': (input) => { // In this case, input is not a single string but an array // of strings. return input.length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { favorite_colors: input }}); }, 'Warning': 'You must select at least one color!' }} ``` ## Input Default Value You can also provide a default value for the input by providing a `Default` property. For text-based inputs such as text and password, whatever you pass as the value of this property will be what's written by default on the input field. ```javascript {'Input': { 'Text': 'What is your name?', 'Default': 'Jane Doe', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!' }} ``` For option-based inputs such as select, radio and checkbox, your `Default` property will have to match one of the value properties of the options you provided: ```javascript {'Input': { 'Text': 'What are your favorite colors?', 'Type': 'checkbox', 'Default': 'orange', 'Options': [ { label: 'Pink', value: 'pink', }, { label: 'Red', value: 'red', }, { label: 'Orange', value: 'orange', }, { label: 'Blue', value: 'blue', }, { label: 'Yellow', value: 'yellow', }, { label: 'Green', value: 'green', } ], 'Validation': (input) => { // In this case, input is not a single string but an array // of strings. return input.length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { favorite_colors: input }}); }, 'Warning': 'You must select at least one color!' }} ``` ## Input Action String By default, the submit button in an input has the text `'OK'` in it, however this may not match the purpose or context of your input. This text can be changed by providing a translation key as the value for the `actionString` property. First, you'll need to register your new string, if your game is a multilanguage one, you'll have to register it for all of the languages your game is available on. Otherwise, you will only need to register in the default language of your game. ```javascript monogatari.translation ('English', { 'EnterCode': 'Enter Code' }); monogatari.translation ('Español', { 'EnterCode': 'Ingresar Código' }); ``` Once you've registered your translation string, you can pass it to the input: ```javascript {'Input': { 'Text': 'Enter the secret code', 'Type': 'password', 'actionString': 'EnterCode', 'Validation': (input) => { // Check what the player entered against our code return input.trim () === 'SecretC0de'; }, 'Save': (input) => { // Do something here, might not be necessary to // save anything for password inputs. }, 'Revert': () => { // Revert what we did in the save function }, 'Warning': 'That\'s not the right code.' }} ``` Your input will then show the text of your string rather than the default one: ![](https://cdn.restlessdreams.cloud/ec5aceab-eec9-4ff0-b572-1801c3910451.webp) ## Input Attributes HTML inputs allow you to set some very useful attributes for them, such as the max and min values they allow. You'll be able to set these attributes using the `Attributes` property. ```javascript {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim ().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input }}); }, 'Revert': () => { monogatari.storage ({ player: { name: '' }}); }, 'Warning': 'You must enter a name!', 'Attributes': { 'placeholder': 'Enter your name', 'minlength': 3, 'maxlength': 20 } }} ``` ### Available Attributes The following table shows the possible attributes you can set. Some may only be available for a certain type of input. If you have doubts on the usage of these attributes, you should refer to the [documentation for the HTML input element and its types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). | Attribute | Description | | :--- | :--- | | `maxlength` | The maximum number of characters the input should accept. For numeric inputs you should use the `max` attribute instead. | | `minlength` | The minimum number of characters long the input can be and still be considered valid. For numeric inputs you should use the `min` attribute instead. | | `placeholder` | An exemplar value to display in the input field whenever it is empty. | | `pattern` | A regular expression the input's contents must match in order to be valid. | | `max` | The maximum value to accept for this input. | | `min` | The minimum value to accept for this input. | | `step` | A stepping interval to use when using up and down arrows to adjust the value, as well as for validation. The amount a numeric value will increment or decrement by. | ## Related Actions - [Choices](/v2/script-actions/choices) - Present selectable options to players - [Functions](/v2/script-actions/javascript) - Run JavaScript in your script - [Message](/v2/script-actions/message) - Show modal messages to players --- # Hide Video > Stop and remove a video from the screen Source: https://monogatari.io/v2/script-actions/hide-video Section: Documentation ## Description ```javascript 'hide video <video_id> [with <animation>]' ``` The `hide video` action stops and removes a video currently playing on the screen. Action ID: `Hide::Video` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | video_id | `string` | The ID of the video to hide (same ID used in `show video`) | | animation | `string` | Optional. Exit animation from [Animate.css](https://daneden.github.io/animate.css/) | ## Examples ### Basic Hide Stop and remove a video immediately: ```javascript 'hide video rain' ``` ### Hide with Animation Remove a video with a fade out effect: ```javascript 'hide video news_broadcast with fadeOut' ``` ### Complete Example ```javascript monogatari.assets('videos', { 'rain': 'rain_loop.webm', 'tv_static': 'static.mp4' }); monogatari.script({ 'Start': [ // Show a looping background video 'show video rain background with loop', 'e The rain has been falling all day.', // Show another video 'show video tv_static displayable', 'e The TV signal is acting up again.', // Hide the TV video with animation 'hide video tv_static with fadeOut', 'e Finally, some peace and quiet.', // Hide the rain 'hide video rain', 'show scene sunny_day with fadeIn', 'e Oh, the sun is coming out!', 'end' ] }); ``` ## Behavior When hiding a video: 1. The video playback is stopped 2. Video resources are cleaned up to prevent memory leaks 3. If an animation is specified, it plays before removal 4. The element is removed from the DOM ### Animation Behavior When using an animation: - The video's `data-visibility` attribute is set to `invisible` - The animation plays - Once the animation ends, the video element is removed ## Error Handling If the video ID doesn't match any currently playing video, the action completes silently without error. ## Related Actions - [Show Video](/v2/script-actions/show-video) - Display a video - [Hide Image](/v2/script-actions/hide-image) - Remove an image - [Hide Character](/v2/script-actions/hide-character) - Remove a character sprite --- # Hide Particles > Hide a particle system animation Source: https://monogatari.io/v2/script-actions/hide-particles Section: Documentation ## Description ```javascript 'hide particles' ``` This `hide` action will stop the currently shown particle system. To learn more about the particle systems, read the [Show Particles documentation](/v2/script-actions/particles). Action ID: `Particles::Hide` Reversible: Yes Requires User Interaction: No ## Parameters None ## Examples The following sample will show the particle system named snow, previously declared on the [particles action configuration](/v2/script-actions/particles#configuration) and then hide it. Script ```javascript Monogatari.script ({ 'Start': [ 'show particles snow', 'Snow is now falling from the sky!', 'hide particles', 'There is no more snow :(' 'end' ] }); ``` Particles Configuration ```javascript Monogatari.action('Particles').particles({ 'snow': { 'particles': { 'number': { 'value': 400, 'density': { 'enable': true, 'value_area': 800 } }, 'color': { 'value': '#fff' }, 'shape': { 'type': 'circle', 'stroke': { 'width': 0, 'color': '#000000' }, 'polygon': { 'nb_sides': 5 }, 'image': { 'src': 'img\/github.svg', 'width': 100, 'height': 100 } }, 'opacity': { 'value': 0.5, 'random': true, 'anim': { 'enable': false, 'speed': 1, 'opacity_min': 0.1, 'sync': false } }, 'size': { 'value': 10, 'random': true, 'anim': { 'enable': false, 'speed': 40, 'size_min': 0.1, 'sync': false } }, 'line_linked': { 'enable': false, 'distance': 500, 'color': '#ffffff', 'opacity': 0.4, 'width': 2 }, 'move': { 'enable': true, 'speed': 6, 'direction': 'bottom', 'random': false, 'straight': false, 'out_mode': 'out', 'bounce': false, 'attract': { 'enable': false, 'rotateX': 600, 'rotateY': 1200 } } }, 'interactivity': { 'detect_on': 'canvas', 'events': { 'onhover': { 'enable': true, 'mode': 'bubble' }, 'onclick': { 'enable': true, 'mode': 'repulse' }, 'resize': true }, 'modes': { 'grab': { 'distance': 400, 'line_linked': { 'opacity': 0.5 } }, 'bubble': { 'distance': 400, 'size': 4, 'duration': 0.3, 'opacity': 1, 'speed': 3 }, 'repulse': { 'distance': 200, 'duration': 0.4 }, 'push': { 'particles_nb': 4 }, 'remove': { 'particles_nb': 2 } } }, 'retina_detect': true } }); ``` --- # Hide Image > Remove an image from the screen Source: https://monogatari.io/v2/script-actions/hide-image Section: Documentation ## Description ```javascript 'hide image <image_id> [at <position>] [with <animation> [classes] [properties]]' ``` The hide image action removes an image from the screen. The image must have been previously shown using [Show Image](/v2/script-actions/show-image). Action ID: `Hide::Image` Reversible: Yes Requires User Interaction: No ## Parameters | Name | Type | Description | | :--- | :--- | :--- | | image_id | `string` | The asset ID or filename used when showing the image | | position | `string` | Optional. CSS class for repositioning before hiding | | animation | `string` | Optional. Exit animation from [Animate.css](https://daneden.github.io/animate.css/) | | classes | `string` | Optional. Additional CSS classes | | properties | `string` | Optional. Properties like `duration` | ## Properties | Property | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` (e.g., `duration 2s`) | ## Examples ### Basic Hide Remove an image immediately without animation: ```javascript 'hide image flower' ``` ### Hide with Animation Remove with an exit animation: ```javascript 'hide image flower with fadeOut' ``` ### Hide with Duration Control how long the animation takes: ```javascript 'hide image flower with fadeOut duration 3s' ``` ### Hide with Position Change Move the image before hiding: ```javascript 'hide image flower at right with slideOutRight' ``` ### Using Filename If the image wasn't declared as an asset: ```javascript 'hide image flower.png with fadeOut' ``` ## Animation Behavior When hiding with an animation: 1. The image's `data-visibility` attribute is set to `invisible` 2. The animation plays 3. Once the animation ends, the element is removed from the DOM This ensures the animation completes before the image disappears. ## Complete Example ```javascript monogatari.assets('images', { 'flower': 'flower.png', 'butterfly': 'butterfly.png' }); monogatari.script({ 'Start': [ 'show scene garden with fadeIn', 'show image flower at left with fadeIn', 'A beautiful flower blooms.', 'show image butterfly at right with bounceIn', 'A butterfly comes to visit!', // Hide with different animations 'hide image butterfly with zoomOut duration 1s', 'The butterfly flies away.', 'hide image flower with fadeOut duration 2s', 'The flower wilts.', 'end' ] }); ``` ## Related Actions - [Show Image](/v2/script-actions/show-image) - Display an image on screen - [Hide Character](/v2/script-actions/hide-character) - Remove a character sprite - [Show Scene](/v2/script-actions/show-scene) - Change background (also removes all images) --- # Hide Character > Remove a character's sprite from screen Source: https://monogatari.io/v2/script-actions/hide-character Section: Documentation ## Description ```text 'hide character <character_id> [at <position>] [with <animation> [classes] [properties]]' ``` The hide character action removes a character's sprite from the screen. If the character was shown with an `end-<animation>` property, that animation will play automatically when hiding. Action ID: `Hide::Character` Reversible: Yes Requires User Interaction: No ## Syntax ### Positions The optional `at <position>` clause can move the character to a different position before applying the hide animation: ```javascript 'hide character e at right with fadeOut' ``` ### Properties | Name | Description | | :--- | :--- | | `duration` | Sets `animation-duration` CSS property. Format: `duration <time>` (e.g., `duration 2s`) | ## Examples ### Basic Hide Remove a character immediately (no animation): ```javascript 'hide character e' ``` ### Hide with Animation Remove a character with a [CSS animation](https://daneden.github.io/animate.css/): ```javascript 'hide character e with fadeOut' ``` ### Hide with Duration Control how long the hide animation takes: ```javascript 'hide character e with fadeOut duration 3s' ``` ### Hide with Position Change Move the character before hiding: ```javascript 'hide character e at right with slideOutRight' ``` ### Using End Animations When a character is shown with `end-<animation>`, that animation automatically plays when hiding: ```javascript // Show with exit animation prepared 'show character e normal with fadeIn end-fadeOut', 'e Hello!', // The fadeOut will play automatically 'hide character e' ``` This is equivalent to: ```javascript 'show character e normal with fadeIn', 'e Hello!', 'hide character e with fadeOut' ``` ## Error Handling The action will show an error if: 1. Character not found: The character ID doesn't exist in the character definitions 2. Character not shown: Attempting to hide a character that isn't currently displayed ## Complete Example ```javascript monogatari.script({ 'Start': [ 'show character e normal at left with fadeIn end-fadeOut', 'show character y happy at right with fadeIn', 'e Hi Yui!', 'y Hello Evelyn!', // Evelyn will fade out (using end-fadeOut) 'hide character e', 'y Where did she go?', // Yui slides out to the right over 2 seconds 'hide character y at right with slideOutRight duration 2s' ] }); ``` ## Related Actions - [Show Character](/v2/script-actions/characters) - Display a character on screen - [Character Layers](/v2/script-actions/character-layers) - Hide individual sprite layers --- # Hide Canvas Source: https://monogatari.io/v2/script-actions/hide-canvas Section: Documentation ## Description ```javascript 'hide canvas <canvas_id> [with [animations] [classes]]' ``` The `hide canvas` action allows you to stop and remove a canvas object. To show a canvas, check the [`Show Canvas action`](/v2/script-actions/canvas). Action ID: `Hide::Canvas` Reversible: Yes Requires User Interaction: No --- # Gallery > An Image Gallery of images for your players to unlock Source: https://monogatari.io/v2/script-actions/image-gallery Section: Documentation New to Monogatari v2 is an Image Gallery feature. With it you can create a gallery of images that your players can unlock by going through the game and seeing all the images, like you will find in many visual novels. Action ID: `Gallery` Reversible: Yes Requires User Interaction: No ## Creating the Gallery By default, the Image Gallery doesn't appear, since it would be pretty disappointing to your players to see a Gallery button on the main menu and have nothing inside of it. ![Monogatari's Default Main Menu with no Gallery](https://cdn.restlessdreams.cloud/de5fbef1-6ae6-4e59-93c5-ad3781d195e7.webp) This is easily fixed by simply declaring some images! First you put some images in the Gallery folder. If you don't already have a Gallery folder because you previously updated the Engine Folder from an earlier version of Monogatari v2, then you may create a new one. ![The "gallery" folder is located inside of your "assets" folder in your game's directory.](https://cdn.restlessdreams.cloud/d75b8193-b8ef-499f-976e-eba6bad63e14.webp) Once you have an image or images in the gallery folder, you'll declare them in `script.js` . ```javascript monogatari.assets ('gallery', { 'someImage': 'happy-shine.png' }); ``` Once that's done, you'll see that a new option has appeared on the Main Screen of your game. ![Monogatari's Default Main Menu with the Gallery option available.](https://cdn.restlessdreams.cloud/010e3126-4a0d-4033-8eb1-bc39e40fca9d.webp) ## Unlocking Gallery Images By default, on a fresh new game, all gallery images are locked, as these are rewards for the player for having completed parts of the game and met certain conditions. ![The default Gallery screen with one image, with that one image being locked.](https://cdn.restlessdreams.cloud/ed4507b4-e470-4b53-896a-5089e723e619.webp) In order for the player to see this locked image, the player must reach a part of the script that enables it. To make this possible for your player, you'll include `"gallery unlock"` in your game script. ```javascript "y You've unlocked the gallery image", "gallery unlock someImage", //unlocks the image "y Great job!" ``` Once the player crosses over this line in the script, it will unlock the gallery image! ![The default Gallery screen with one image, with that one image being Unlocked.](https://cdn.restlessdreams.cloud/97bb392c-2ea4-4741-b174-58afc3a3d9ab.webp) Monogatari gallery unlocks are not dependent on any save files, so if you, for whatever reason, want to lock the player out of being able to see any of the gallery images for any reason, like as part of, for instance, a story event that master resets the game, which includes losing the gallery, you may re-lock images by writing `"gallery lock someImage"` in your script. ```javascript "y This will lock the image away so that you can't see it anymore.", "gallery lock someImage", "y Goodbye, Protagonist-sama. I'll never forget you." ``` --- # End > End your game Source: https://monogatari.io/v2/script-actions/end Section: Documentation ## Description ```text 'end' ``` The `end` action terminates the game and returns to the main menu. It resets all storage, actions, and components to their initial state. Action ID: `End` Reversible: No Requires User Interaction: No ## Behavior When the `end` action is executed: 1. All screens are hidden 2. The `playing` global is set to `false` 3. The game is fully reset (state, history, storage) 4. The main menu is displayed 5. UI elements are restored to their initial state ## Usage Every script path should end with the `end` action: ```javascript monogatari.script({ 'Start': [ 'Hello, this is my visual novel!', 'Thank you for playing!', 'end' ] }); ``` ### Multiple Endings You can have multiple endings in your game: ```javascript monogatari.script({ 'Start': [ 'y Do you want the good ending or bad ending?', {'Choice': { 'Good': { 'Text': 'Good ending', 'Do': 'jump GoodEnd' }, 'Bad': { 'Text': 'Bad ending', 'Do': 'jump BadEnd' } }} ], 'GoodEnd': [ 'y Everything worked out perfectly!', 'centered THE GOOD END', 'end' ], 'BadEnd': [ 'y Things didn\'t go so well...', 'centered THE BAD END', 'end' ] }); ``` ## Keyboard Shortcut Players can trigger a quit confirmation using Shift+Q during gameplay. This displays an alert with: - Quit button - Ends the game - Cancel button - Dismisses the alert This shortcut is automatically registered when the game initializes. ## Electron/Desktop Integration When running in Electron (desktop builds), if the game is not currently playing and the quit action is triggered, a quit request is sent to the Electron process to close the application window. ## Important Notes > [!WARNING] > The `end` action is not reversible. Once executed, the player cannot use the back button to return to the game. Make sure to provide save opportunities before critical endings. ## Examples ### Simple Ending ```javascript monogatari.script({ 'Start': [ 'y Welcome to my story.', 'y And that\'s the end!', 'end' ] }); ``` ### Ending with Credits ```javascript monogatari.script({ 'Start': [ 'show scene sunset with fadeIn', 'y Thank you for playing...', 'wait 2000', 'show scene black with fadeIn', 'centered Thanks for playing!', 'wait 3000', 'end' ] }); ``` ### Ending After Unlocking Gallery ```javascript monogatari.script({ 'Start': [ // Game content... 'y You reached the true ending!', // Unlock gallery item function() { monogatari.storage().game.gallery.trueEnd = true; return true; }, 'centered TRUE END', 'end' ] }); ``` ## Related Actions - [Jump](/v2/script-actions/jump) - Navigate to different labels - [Clear](/v2/script-actions/clear) - Clear the text box --- # Dialogs > The text your players are going to read. Source: https://monogatari.io/v2/script-actions/dialogs Section: Documentation ## Description ```javascript '[character_id][:<expression_id>][:<class_names>] <dialog_text>' ``` Dialogs are the primary way to display text to the player. Any statement in your script that doesn't match any other action will be displayed as dialog. Action ID: `Dialog` Reversible: Yes Requires User Interaction: Yes (player must click/tap to proceed) Related Components: [Text Box](/v2/components/text-box) ## Syntax The full dialog syntax is: ```text [identifier][:<expression>][:<classes>] <text> ``` | Part | Required | Description | | :--- | :--- | :--- | | identifier | No | Character ID, `centered`, `nvl`, or `narrator`. If omitted, treated as narrator dialog. | | expression | No | Expression/side image to show (only for characters with defined expressions). | | classes | No | Custom CSS classes separated by `\|` (pipe). | | text | Yes | The dialog text to display. Supports HTML and [text effects](#text-effects). | ## Dialog Types ### Narrator Dialogs Any statement that doesn't start with a recognized character ID, `centered`, or `nvl` is displayed as a narrator dialog. Narrator dialogs don't show a name in the text box. ```javascript 'The sun was setting over the horizon.' 'It was a peaceful evening.' ``` You can also explicitly use `narrator`: ```javascript 'narrator The story begins here...' ``` ### Character Dialogs To make a character speak, prefix the dialog with their character ID: ```javascript 'y Hi! My name is Yui.' ``` The character's name (as defined in their character declaration) will be displayed in the text box. #### With Expression/Side Image If you've defined `expressions` in your character declaration, you can specify which expression to show: ```javascript 'y:happy Hi! I am so glad to meet you!' 'y:sad But I have to go now...' ``` The expression image appears as a side image next to the text. #### Default Expression If a character has a `default_expression` defined, it will be shown automatically when no expression is specified: ```javascript // Character definition monogatari.characters({ 'y': { name: 'Yui', color: '#ff0000', default_expression: 'normal', expressions: { 'normal': 'yui_normal.png', 'happy': 'yui_happy.png', 'sad': 'yui_sad.png' } } }); // In script - will show 'normal' expression 'y Hello there!' ``` ### Centered Dialogs The `centered` keyword displays text in a floating box in the center of the screen, hiding the regular text box: ```javascript 'centered This is a dramatic moment.' ``` Centered dialogs use the `<centered-dialog>` component instead of `<text-box>`. ### NVL Dialogs NVL (Novel) mode displays multiple lines of dialog on screen at once, similar to visual novels like Fate/stay Night. The screen fills up with consecutive dialog entries. ```javascript 'nvl The rain continued to fall.', 'nvl I stood there, watching the droplets hit the window.', 'nvl Each one seemed to carry a memory with it.' ``` #### NVL Characters Characters can be set to always use NVL mode by adding `nvl: true` to their definition: ```javascript monogatari.characters({ 'narrator_nvl': { name: '', nvl: true } }); // This will automatically use NVL mode 'narrator_nvl A long time ago, in a distant land...' ``` Note: Side images/expressions are not supported in NVL mode. ## Custom Classes You can apply custom CSS classes to the text-box (or centered-dialog) element by adding them after the expression: ```javascript 'y:happy:highlight Hello!' // Single class 'y:sad:warning|urgent Important!' // Multiple classes (pipe-separated) 'narrator::thought A quiet thought' // No expression, just class 'centered::dramatic A revelation!' // Centered with class ``` Classes are reset on every dialog, so you must include them on each dialog where you want them applied. ### Example CSS for Custom Classes ```css text-box.highlight { background: rgba(255, 255, 0, 0.3); } text-box.warning { border: 2px solid red; } centered-dialog.dramatic { font-size: 2em; text-shadow: 0 0 10px white; } ``` ## Clear Command The `clear` command removes all text from the dialog area: ```javascript 'clear' ``` The clear command automatically advances to the next statement without requiring player interaction. Use a `wait` command after it if you want the player to see a blank dialog box: ```javascript 'y I need a moment to think...', 'clear', 'wait 2000', 'y Okay, I have decided!' ``` ## Text Effects Dialogs support inline text effects using special markers. These are processed by the TypeWriter component. ### Pause Pause the typing animation for a specified duration: ```javascript 'y Hello...{pause:1000} Are you there?' ``` The `{pause:N}` marker pauses for N milliseconds. ### Speed Change the typing speed mid-dialog: ```javascript 'y This is normal speed. {speed:50}This is slower. {speed:200}This is faster!' ``` The `{speed:N}` marker changes speed as a percentage (100 = normal, 50 = half speed, 200 = double speed). ### Visual Effects Enclosed effects apply visual styling to text. Use `{effect}text{/effect}` syntax: Animation Effects: - `{shake}text{/shake}` - Shaking text - `{shake-hard}`, `{shake-slow}`, `{shake-little}`, `{shake-horizontal}`, `{shake-vertical}` - Shake variants - `{wave}text{/wave}` - Wavy text animation - `{wave-slow}`, `{wave-fast}` - Wave speed variants - `{fade}text{/fade}` - Fading text - `{fade-slow}` - Slow fade - `{blur}text{/blur}` - Blurry text - `{scale}text{/scale}` - Scaling animation - `{scale-bounce}` - Bouncy scaling - `{slide-up}`, `{slide-down}` - Sliding animations - `{glitch}text{/glitch}` - Glitch effect - `{glitch-hard}`, `{glitch-slow}` - Glitch variants - `{flicker}text{/flicker}` - Flickering text Style Effects: - `{bold}text{/bold}` - Bold text - `{italic}text{/italic}` - Italic text - `{big}text{/big}` - Larger text - `{small}text{/small}` - Smaller text - `{strike}text{/strike}` - Strikethrough - `{redacted}text{/redacted}` - Redacted/censored style - `{invisible-ink}text{/invisible-ink}` - Hidden until hover - `{handwriting}text{/handwriting}` - Handwritten style Emotion Effects: - `{angry}text{/angry}` - Angry styling - `{scared}text{/scared}` - Scared styling - `{happy}text{/happy}` - Happy styling - `{sad}text{/sad}` - Sad styling - `{mysterious}text{/mysterious}` - Mysterious styling - `{excited}text{/excited}` - Excited styling - `{whisper}text{/whisper}` - Whisper styling - `{shout}text{/shout}` - Shouting styling - `{dizzy}text{/dizzy}` - Dizzy effect - `{dreamy}text{/dreamy}` - Dreamy effect - `{robotic}text{/robotic}` - Robotic styling - `{static}text{/static}` - Static/noise effect - `{rainbow}text{/rainbow}` - Rainbow colors - `{glow}text{/glow}` - Glowing text - `{impact}text{/impact}` - Impact/emphasis styling ### Combining Effects You can combine multiple effects and markers: ```javascript 'y I am {angry}so frustrated{/angry}!{pause:500} {whisper}But I will be okay{/whisper}...' ``` ## HTML Support Dialogs support inline HTML for additional formatting: ```javascript 'y The <span class="highlight">important</span> thing is...' 'y Press the <i class="fa fa-arrow-left"></i> button to go back.' ``` ## Related Settings | Setting | Default | Description | | :--- | :--- | :--- | | `TypeAnimation` | `true` | Enable/disable typing animation globally | | `NVLTypeAnimation` | `true` | Enable/disable typing animation in NVL mode | | `CenteredTypeAnimation` | `true` | Enable/disable typing animation for centered dialogs | | `NarratorTypeAnimation` | `true` | Enable/disable typing animation for narrator | | `TextSpeed` | varies | Typing speed (lower = faster). Configurable by player in settings. | ## Related Components - [Text Box](/v2/components/text-box) - The component that displays dialogs - [Dialog Log](#dialog-log) - View history of dialogs ## Dialog Log The dialog log stores all dialogs displayed during gameplay. Players can access it via the quick menu to review past conversations. The log is automatically populated as dialogs are shown and supports scrolling through the entire conversation history. --- # Conditionals > Control the flow of your game based on conditions Source: https://monogatari.io/v2/script-actions/conditionals Section: Documentation ## Description ```javascript {'Conditional': { 'Condition': function() { /* return true/false or string / }, 'True': '<statement>', 'False': '<statement>' }} ``` Conditionals allow you to control the flow of your game based on conditions. You can show different dialogs, jump to different labels, or execute different actions depending on storage values, player choices, or any other condition. Action ID: `Conditional` Reversible: Yes Requires User Interaction: Depends on the branch statement executed ## Basic Structure | Property | Type | Description | | :--- | :--- | :--- | | `Condition` | `function` | Function that returns `true`, `false`, or a string key | | `True` | `statement` | Statement to execute if condition returns `true` | | `False` | `statement` | Statement to execute if condition returns `false` | | `<custom>` | `statement` | Custom branches when using string return values | ## Examples ### Boolean Condition Check if a condition is true or false: ```javascript {'Conditional': { 'Condition': function () { return this.storage('evelyn_name') === 'Evelyn'; }, 'True': "e Evelyn... That's a lovely name! I love it!", 'False': 'e {{evelyn_name}}... Yeah, sounds good!' }}, ``` ### Conditional Jump Jump to different labels based on a condition: ```javascript {'Conditional': { 'Condition': function () { return this.storage('played'); }, 'True': 'jump ReturningPlayer', 'False': 'jump NewGame' }}, ``` ### Multiple Branches (String Returns) Use string return values for more than two branches: ```javascript {'Conditional': { 'Condition': function () { const money = this.storage().money; if (money < 1) { return 'broke'; } else if (money < 5) { return 'poor'; } else if (money < 20) { return 'comfortable'; } else { return 'rich'; } }, 'broke': 'jump GoHomeHungry', 'poor': 'jump BuySnack', 'comfortable': 'jump BuyMeal', 'rich': 'jump BuyFeast' }}, ``` ### Numeric String Branches Use numbers as string keys for indexed branches: ```javascript {'Conditional': { 'Condition': function () { // Convert number to string for branch key const affection = this.storage().affection; if (affection >= 100) return '3'; if (affection >= 50) return '2'; if (affection >= 25) return '1'; return '0'; }, '0': 'e I barely know you.', '1': "e We're acquaintances, I suppose.", '2': "e You're a good friend.", '3': 'e You mean everything to me!' }}, ``` ### Complex Condition Combine multiple checks: ```javascript {'Conditional': { 'Condition': function () { const hasKey = this.storage().inventory.includes('key'); const metGuard = this.storage().flags.metGuard; if (hasKey && metGuard) { return 'full_access'; } else if (hasKey) { return 'has_key'; } else if (metGuard) { return 'knows_guard'; } return 'False'; }, 'full_access': 'jump EnterCastle', 'has_key': 'e The guard stops me. I have a key but no permission.', 'knows_guard': 'e The guard lets me pass, but the door is locked.', 'False': "e I can't get in here." }}, ``` ## Important Notes > [!WARNING] > All branches must be defined! Monogatari throws an error if the Condition returns a value that doesn't match any branch key. Always account for all possible return values. ### String vs Boolean - Return `true` → executes `'True'` branch - Return `false` → executes `'False'` branch - Return `'someString'` → executes `'someString'` branch ### Numeric Return Values When the `Condition` returns a `number`, Monogatari coerces it into a string and uses it as the branch key (so returning `2` selects the `'2'` branch). For this to work, the number must be a non-negative integer. > [!WARNING] > A negative number or a non-integer (such as `-1` or `1.5`) returned from the `Condition` is invalid and will raise an error instead of selecting a branch. If you need fractional or negative logic, map it to a non-negative integer or to a string key inside your `Condition` function. ### Errors Inside the Condition If the `Condition` function throws an error (or returns a rejected `Promise`), Monogatari does not crash the game. Instead, it falls back to running the `'False'` branch. > [!NOTE] > The `'False'` branch also runs whenever the `Condition` returns any value that is neither `true` nor a string nor a valid numeric key (for example `false`, `undefined`, `null`, or `NaN`). Because a thrown error is treated the same way, make sure a `'False'` branch is always defined when your condition can fail. ### Async Conditions Conditions can use Promises for async operations: ```javascript {'Conditional': { 'Condition': async function () { const result = await someAsyncCheck(); return result; }, 'True': 'e The async check passed!', 'False': 'e The async check failed.' }}, ``` ## Rollback Behavior Conditionals support rollback. When the player goes back: - The previously executed branch is reverted - The condition is re-evaluated on the next forward progression ## Related Actions - [Jump](/v2/script-actions/jump) - Navigate to different labels - [Choices](/v2/script-actions/choices) - Let players choose branches - [Functions](/v2/script-actions/javascript) - Run JavaScript code --- # Clear > Clear the text box Source: https://monogatari.io/v2/script-actions/clear Section: Documentation ## Description ```text 'clear' ``` The `clear` action removes all dialog content from the text box, leaving it blank. This is useful for scene transitions, dramatic pauses, or resetting the display between sections. Action ID: `Clear` Reversible: Yes Requires User Interaction: No ## Behavior When the `clear` action is executed: 1. Calls the Dialog action's reset method 2. Preserves and saves NVL mode state (if active) 3. Records the text box mode in history for rollback support 4. Automatically advances to the next statement ### NVL Mode Handling The `clear` action has special handling for NVL (Novel) mode: - If NVL mode is active, it's preserved (`keepNVL: true`) - The current NVL state is saved for potential rollback (`saveNVL: true`) - On rollback, NVL mode can be restored if it was active ## Basic Usage ```javascript monogatari.script({ 'Start': [ 'y Hello there!', 'y How are you today?', 'clear', 'y Now the text box is empty.', 'end' ] }); ``` ## Use Cases ### Scene Transitions Clear the dialog before changing scenes: ```javascript monogatari.script({ 'Start': [ 'show scene bedroom', 'y I should get some rest.', 'clear', 'show scene black with fadeIn', 'wait 1000', 'show scene bedroom_morning with fadeIn', 'y A new day begins!', 'end' ] }); ``` ### Dramatic Pauses Create dramatic moments by clearing the text: ```javascript monogatari.script({ 'Start': [ 'y I have something important to tell you...', 'clear', 'wait 2000', 'y I\'m leaving tomorrow.', 'end' ] }); ``` ### Chapter Breaks Use clear to separate chapters or sections: ```javascript monogatari.script({ 'Start': [ 'y And that concludes Chapter 1.', 'clear', 'centered Chapter 2', 'clear', 'show scene new_location', 'y The story continues...', 'end' ] }); ``` ### Before Centered Text Clear the text box before displaying centered text: ```javascript monogatari.script({ 'Start': [ 'y This is the end of our journey.', 'clear', 'centered THE END', 'wait 3000', 'end' ] }); ``` ### NVL Mode Clearing In NVL mode, clear removes all accumulated dialog but keeps NVL mode active: ```javascript monogatari.script({ 'Start': [ 'nvl', // Enable NVL mode 'y:nvl First line of dialog.', 'y:nvl Second line of dialog.', 'y:nvl Third line of dialog.', 'clear', // Clears all lines but stays in NVL mode 'y:nvl New page of dialog.', 'end' ] }); ``` ## Rollback Behavior The `clear` action supports rollback: - When going back past a `clear`, the previous dialog state is restored - If NVL mode was active when `clear` was executed, it will be restored on rollback - The engine tracks the text box mode (ADV or NVL) in history ## Examples ### Full Scene Change ```javascript monogatari.script({ 'Start': [ 'show scene cafe', 'show character e happy at center', 'e Let\'s meet again sometime!', 'clear', 'hide character e with fadeOut', 'show scene black with fadeIn', 'wait 1500', 'show scene home with fadeIn', 'y I\'m finally home.', 'end' ] }); ``` ### Conversation Reset ```javascript monogatari.script({ 'Start': [ 'y Do you remember our first conversation?', 'clear', // Flashback 'show scene park_old with sepia', 'y:past Hello, nice to meet you!', 'e:past Hi there!', 'clear', // Return to present 'show scene park', 'y Those were good times.', 'end' ] }); ``` ## Related Actions - [Dialog](/v2/script-actions/dialogs) - Display character dialog - [Wait](/v2/script-actions/wait) - Pause execution - [Jump](/v2/script-actions/jump) - Jump to another label - [End](/v2/script-actions/end) - End the game --- # Choices > Learn about choices, their properties and how to use them! Source: https://monogatari.io/v2/script-actions/choices Section: Documentation ![](https://cdn.restlessdreams.cloud/758f1f9d-78be-4801-b0ab-5384e4b3a48c.webp) ## Overview Choices allow players to take decisions and then react based on whatever they chose. They are represented on your script as `Objects` and they allow you to define as many choices as you can fit on the screen! Action ID: `Choice` Reversible: Yes Requires User Interaction: Yes ## Global Properties | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `Class` | `string` | Yes | A space separated list of classes to add to the choice container. | | `Dialog` | `string` | Yes | Specifies a dialog to be shown along with the choices. | | `Timer` | `object` | Yes | Adds a countdown timer to the choices that runs a callback when time expires. See [Timed Choices](#timed-choices). | | `...Choices` | `Objects` | No | Any other object added will be considered as a choice. Choices have their own individual properties that are described below. | ## Choices Properties | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `Class` | `string` | Yes | A space separated list of classes to add to the choice. | | `Clickable` | `function` | Yes | A function returning a `boolean`, whether the option should allow to be clicked or not, effectively disabling a choice while still showing it if needed. | | `Condition` | `function` | Yes | A function returning a `boolean`, whether the choice should be shown or not. | | `Do` | `statement` | No | The action to perform if the the choice is picked. Contrary to the `onChosen` property, this one should be a Monogatari statement, meaning it can be anything you are able to use in your script. | | `onChosen` | `function` | Yes | A function that will be run if the choice is picked. | | `onRevert` | `function` | Yes | A function that will revert the actions done on the `onChosen` function of the choice should the player go back. | | `Text` | `string` | No | The text that will be shown in the choice. | ## Examples Every choice requires 2 properties: the text to display and what to do when it's clicked. ```javascript {'Choice': { 'Developer': { 'Text': 'I’m a developer.', 'Do': 'jump Developer' }, 'Writer': { 'Text': 'I’m a writer.', 'Do': 'jump Writer' }, 'Artist': { 'Text': 'I’m an artist.', 'Do': 'jump Artist' }, 'Player': { 'Text': 'I’m a Player.', 'Do': 'jump Player' } }} ``` ### Conditional Choices There are some cases where you would only want to show a choice if certain conditions are met. For this example, let's assume this is your `storage` variable: ```javascript 'use strict'; // Persistent Storage Variable monogatari.storage ({ played: false }); ``` As you can see, we added a 'played' variable inside the storage and set its default to `false`. Now, let's see what would happen with the following Choices: ```javascript {'Choice': { 'Developer': { 'Text': 'I’m a developer.', 'Do': 'jump Developer' }, 'Player': { 'Text': 'I’m a Player.', 'Do': 'jump Player', 'Condition': function () { return this.storage ('played'); // The 'Player' option will only be shown if this returns true. } } }} ``` `'Player'` will only be shown if the `'played'` variable we added is `true`, since we defined it as `false`, then it won't be shown however, if somewhere along the script we were to change that variable to `true` then this choice will be shown. ### Showing Text when Showing the Choices You might want to show a dialog along with the choices, this is possible using the `Dialog` property inside the object: ```javascript {'Choice': { 'Dialog': 'e Before I continue, let me ask you, what are you?', 'Developer': { 'Text': 'I’m a developer.', 'Do': 'jump Developer' }, 'Player':{ 'Text': 'I’m a Player.', 'Do': 'jump Player', 'Condition': function () { return this.storage ('played'); // The 'Player' option will only be shown if this returns true. } } }} ``` That way the `'Dialog'` property is the one that will be shown with the choices, as you can see, just like with normal dialogs, you can specify what character is the one talking and take full advantage of other things like side images on it. ### Unclickable Choices Earlier we made a conditional choice that would only be shown if a condition was satisfied, but what if you want to show the player that there is a choice they _could_ be making if certain conditions were satisfied. For this example, let's assume this is your `storage` variable: ```javascript 'use strict'; // Persistent Storage Variable monogatari.storage ({ haveKey: false }); ``` As you can see, we added a `haveKey` variable inside the storage and set its default value to `false`. With that established, consider the following code. ```javascript {'Choice':{ 'Dialog': 'Do you unlock the locked door?', 'FirstOption':{ 'Text': 'Yes', 'Do': 'jump label1', 'Clickable': function(){ return this.storage().haveKey } }, 'SecondOption':{ 'Text': 'No', 'Do': 'jump label2' } }}, ``` The `'Clickable'` property, as its name implies, decides whether or not a button can be clicked. `Yes` will be shown regardless of whether or not the variable we added is `true`, but it will only be _clickable_ if it is. On that note, if the variable `haveKey` is false, then the `Yes` button will not be clickable. However, this might be confusing to your players, as they will see a choice, try to click it, and clicking it will do nothing. We can help out with this confusion with a little bit of visual design. ### Styling your Buttons The `'Class'` property allows you to give a CSS class to your buttons for special styles. Suppose you had the following CSS in your `main.css` file: ```css .boldedText { font-weight: bold; } .italicText { font-style: italic; } ``` The `boldedText` and `italicText` classes can then be applied to your buttons by setting their `'Class'` properties in your script, like so: ```javascript {"Choice":{ "FirstOption":{ "Text": "Yes", "Do": "jump label1", "Class": "boldedText" //A css class to apply to the button. }, "SecondOption":{ "Text": "No", "Do": "jump label2", "Class": "italicText" } }}, ``` This way, the `'Yes'` button will have its text bolded and the `'No'` button will have its text _italicized_. You can also use CSS styling to do things like give buttons background images and make the text on them invisible, so you can have buttons with pictures! Earlier, we mentioned you could style unclickable buttons as well. This is easy to do as the buttons in Monogatari's choices are HTML buttons, and when a button is made unclickable, it is given the `'disabled'` attribute. This means that we can style disabled buttons with CSS attribute styling. Consider the following example: ```css [disabled] { opacity: .5; } ``` With this CSS styling, buttons containing the `'disabled'` attribute will render semi-transparent, which will visually indicate to the player that they are different, so hopefully they won't be confused when they are unable to click it. You can also use classes and attributes at the same time: ```css [disabled].classname { text-decoration: line-through; } ``` In this example, the text would have a line through it if and only if it is both disabled, and the button has the `'.classname'` class. If you wanted to make a specific class for a specific button, you could use the `::after` pseudo selector and the `'content'` property to append an explanation as to why you can't click the button too, or you could make two separate buttons where one displays if a condition is met, and the other displays if the condition is unmet. ### onChosen Functions The `'onChosen'` property allows us to run a function when the player clicks your button. For this example, we'll assume that our storage contains the following: ```javascript 'use strict'; // Persistent Storage Variable monogatari.storage ({ enemyHealth: 100, playerAttack: 20 }); ``` In our `script.js` file, somewhere _outside_ of our game's script, we could have a simple example function for attacking the enemy. ```javascript function attackEnemy(){ monogatari.storage().enemyHealth = monogatari.storage().enemyHealth - monogatari.storage().playerAttack }; ``` This function sets the `enemyHealth` value to be equal to its current value minus the `playerAttack` value. Then, in our script, we could have a choice for the player: ```javascript {"Choice":{ "Dialog": "The enemy wants to fight! What do you do?", "FirstOption":{ "Text": "Attack!", "onChosen": function(){attackEnemy()}, "Do": "You attack the enemy for {{playerAttack}} damage!" }, "SecondOption":{ "Text": "Defend", "Do": "You defend instead of attacking." } }}, "The enemy now has {{enemyHealth}} health points left." ``` You could also have the function written out in the script itself for one-time functions that won't be called again. ```javascript {"Choice":{ "Dialog": "The enemy wants to fight! What do you do?", "FirstOption":{ "Text": "Attack!", "onChosen": function (){ monogatari.storage().enemyHealth = monogatari.storage().enemyHealth - monogatari.storage().playerAttack }, "Do": "You attack the enemy for {{playerAttack}} damage!" }, "SecondOption":{ "Text": "Defend", "Do": "You defend instead of attacking." } }}, "The enemy now has {{enemyHealth}} health points left.", ``` This achieves the same result. You could also use these functions to invisibly keep track of which options the player clicked, or any other ideas you might have. ### onRevert The `'onRevert'` property should contain a function that will run when the player rewinds the game using the `back` button before a choice selection that runs an `onChosen` function. Ideally, this function should be used to undo whatever was done by the `onChosen` function, assuming the `onChosen` function did anything at all. For example, if you have an `onChosen` function that gives the player 5 gold, then the `onRevert` function should remove 5 gold, or else the player could just choose the option, rewind, choose it again, until they have as much gold as they want. ```javascript {"Choice":{ "Dialog": "Would you like some Gold?", "Yes": { "Text": "Yes please.", "Do": "p Yes please.", "onChosen": function() { monogatari.storage().playerGold += 5; }, "onRevert": function() { monogatari.storage().playerGold -= 5; } }, "No": { "Text": "No thank you.", "Do": "No thank you.", }, }}, "Okay! As a result of your decision, you now have {{playerGold}} Gold!", ``` Monogatari remembers for the player which option they picked, so if they chose Yes in the above example, when they rewind, it will run the `onRevert` function for "yes", whereas if they chose no, it will not run anything special, as No does not contain an `onRevert` or `onChosen` function. The `'onRevert'` property is required when you use the `onChosen` function, or else the player will not be able to use the "back" button to revert before the choice. If you don't care whether or not your player is allowed to rewind before a decision, then you don't need to use `onRevert` but that might make your player assume that there's a bug if some choices are reversible and others aren't. ### Timed Choices You can add a timer to choices that will automatically select an option or perform an action when time runs out. #### Timer Properties | Name | Type | Description | | :--- | :--- | :--- | | `time` | `number` | Time in milliseconds before the callback is triggered | | `callback` | `function` | Function to run when time expires | #### Basic Timer Example ```javascript {'Choice': { 'Dialog': 'Quick! What do you do?', 'Timer': { time: 5000, // 5 seconds callback: () => { // Get a random choice when time runs out const choices = monogatari.element().find('[data-choice]:not([disabled])'); const random = choices.get(Math.floor(Math.random() choices.length)); random.click(); return Promise.resolve(); } }, 'Fight': { 'Text': 'Fight!', 'Do': 'jump Fight' }, 'Run': { 'Text': 'Run away!', 'Do': 'jump Escape' } }} ``` #### Auto-Select Default Option ```javascript {'Choice': { 'Dialog': 'You have 10 seconds to decide.', 'Timer': { time: 10000, callback: () => { // Click the first available choice const firstChoice = monogatari.element().find('[data-choice]:not([disabled])').first(); firstChoice.click(); return Promise.resolve(); } }, 'Accept': { 'Text': 'Accept the deal', 'Do': 'jump Accept' }, 'Decline': { 'Text': 'Decline', 'Do': 'jump Decline' } }} ``` The timer displays as a progress bar that decreases as time passes. It is automatically cleaned up when a choice is selected or when the player rolls back. ## Related Actions - [Input](/v2/script-actions/input) - Get text input from players - [Jump](/v2/script-actions/jump) - Navigate to different labels --- # Script Actions Source: https://monogatari.io/v2/script-actions Section: Documentation Guides in this section: - [Choices](/v2/script-actions/choices) - [Clear](/v2/script-actions/clear) - [Conditionals](/v2/script-actions/conditionals) - [Dialogs](/v2/script-actions/dialogs) - [End](/v2/script-actions/end) - [Gallery](/v2/script-actions/image-gallery) - [Hide Canvas](/v2/script-actions/hide-canvas) - [Hide Character](/v2/script-actions/hide-character) - [Hide Image](/v2/script-actions/hide-image) - [Hide Particles](/v2/script-actions/hide-particles) - [Hide Text Box](/v2/script-actions/hide-textbox) - [Hide Video](/v2/script-actions/hide-video) - [Input](/v2/script-actions/input) - [Functions](/v2/script-actions/javascript) - [Jump](/v2/script-actions/jump) - [Next](/v2/script-actions/next) - [Pause](/v2/script-actions/pause) - [Placeholder](/v2/script-actions/placeholder) - [Play Music](/v2/script-actions/play-music) - [Play Sound](/v2/script-actions/play-sound) - [Play Voice](/v2/script-actions/play-voice) - [Preload](/v2/script-actions/preload) - [Show Canvas](/v2/script-actions/canvas) - [Show Background](/v2/script-actions/show-background) - [Show Character](/v2/script-actions/characters) - [Show Character Layer](/v2/script-actions/character-layers) - [Show Image](/v2/script-actions/show-image) - [Show Message](/v2/script-actions/message) - [Show Notification](/v2/script-actions/notifications) - [Show Particles](/v2/script-actions/particles) - [Show Scene](/v2/script-actions/show-scene) - [Show Text Box](/v2/script-actions/show-textbox) - [Show Video](/v2/script-actions/show-video) - [Stop Music](/v2/script-actions/stop-music) - [Stop Sound](/v2/script-actions/stop-sound) - [Stop Voice](/v2/script-actions/stop-voice) - [Unload](/v2/script-actions/unload) - [Vibrate](/v2/script-actions/vibrate) - [Wait](/v2/script-actions/wait) --- # Built-in Functions Source: https://monogatari.io/v2/building-blocks/components/built-in-functions Section: Documentation Components come with a series of built-in functions that make it easier to interact with them. ## Static Methods These methods are called on the component class itself. ### configuration Get or set component configuration: ```javascript // Set configuration MyComponent.configuration({ defaultValue: 'something', options: { enabled: true } }); // Get all configuration const config = MyComponent.configuration(); // Get specific property const value = MyComponent.configuration('defaultValue'); ``` ### template Modify the HTML structure of a component without extending the class: ```javascript // Get current template const currentTemplate = monogatari.component('main-screen').template(); // Set new template monogatari.component('main-screen').template(() => { return ` <h1>My Awesome Game</h1> <main-menu></main-menu> `; }); ``` ### all Get all instances of the component as an Artemis DOM object: ```javascript // Get all text-box elements const textBoxes = TextBox.all(); // Hide all instances textBoxes.hide(); ``` ### get Get a specific instance by ID: ```javascript // Get instance with data-instance="main" const mainInstance = MyComponent.get('main'); ``` ### instances Iterate over all component instances: ```javascript // With callback - iterate each instance MyComponent.instances((instance) => { instance.reset(); }); // Without callback - returns Artemis DOM object const allInstances = MyComponent.instances(); ``` ## Instance Methods These methods are available on each component instance. ### setProps / setState Update component properties or state: ```javascript // Set props (triggers onPropsUpdate) this.setProps({ title: 'New Title' }); // Set state (triggers onStateUpdate) this.setState({ count: 5 }); ``` ### forceRender Force the component to re-render: ```javascript async updateContent() { this.state.content = 'New content'; await this.forceRender(); } ``` ### element Get the component as an Artemis DOM instance: ```javascript // Get element for DOM operations const el = this.element(); el.addClass('active'); el.style('opacity', '0.5'); ``` ### content Find a content element inside the component: ```javascript // In component render: render() { return ` <div data-content="header">Header</div> <div data-content="body">Body</div> `; } // Access content areas: const header = this.content('header'); header.html('New Header'); ``` ### remove Remove the component from the DOM: ```javascript // Remove this component instance this.remove(); ``` ### instance Find another instance of the same component type by ID: ```javascript // Find instance with specific ID const otherInstance = this.instance('secondary'); ``` ### parent Get or set the parent component: ```javascript // Set parent this.parent(parentComponent); // Get parent const parent = this.parent(); if (parent) { parent.notifyChild(this); } ``` ## Rendering Methods ### render Define the component's HTML structure. Must be implemented: ```javascript render() { return ` <div class="container"> <h1>${this.props.title}</h1> <p>${this.state.description}</p> <slot></slot> </div> `; } ``` ### Using Slots Content placed inside component tags in HTML is rendered in `<slot>`: ```html  <my-component> <p>This goes in the slot</p> </my-component> ``` ```javascript // In component render() { return ` <div class="wrapper"> <slot></slot>  </div> `; } ``` ## Engine Interaction ### Running Script Actions ```javascript // Run a script action programmatically this.engine.run('show character e happy'); // Run multiple actions this.engine.run([ 'show scene forest', 'play music theme' ]); ``` ### Accessing Game State ```javascript // Get state const label = this.engine.state('label'); const step = this.engine.state('step'); // Set state this.engine.state({ customValue: true }); // Get history const dialogHistory = this.engine.history('dialog'); // Get preferences const language = this.engine.preference('Language'); // Get settings const textSpeed = this.engine.setting('TextSpeed'); ``` ### Finding Elements ```javascript // Find elements in the game const gameScreen = this.engine.element().find('[data-screen="game"]'); // Find specific component const textBox = this.engine.element().find('text-box'); ``` ## DOM Operations Components use Artemis for DOM manipulation: ```javascript // Using element() this.element().addClass('active'); this.element().removeClass('hidden'); this.element().toggleClass('visible'); // Finding children this.element().find('.child-element').html('New content'); // Attributes this.element().attribute('data-value', '123'); const value = this.element().attribute('data-value'); // Styles this.element().style('opacity', '0.5'); this.element().style({ opacity: '0.5', transform: 'scale(1.1)' }); // Events this.element().on('click', (e) => this.handleClick(e)); // Visibility this.element().show(); this.element().hide(); const isVisible = this.element().isVisible(); ``` ## Complete Example ```javascript class NotificationBar extends Monogatari.Component { static _configuration = { duration: 3000, position: 'top' }; constructor() { super(); this.props = { message: '' }; this.state = { visible: false, queue: [] }; } static async setup() { // Add component to game screen this.engine.element().find('game-screen').append( '<notification-bar></notification-bar>' ); } static async bind() { // Listen for custom events document.addEventListener('notify', (e) => { NotificationBar.instances((instance) => { instance.show(e.detail.message); }); }); } async show(message) { this.state.queue.push(message); if (!this.state.visible) { await this.displayNext(); } } async displayNext() { if (this.state.queue.length === 0) { this.setState({ visible: false }); return; } const message = this.state.queue.shift(); this.setProps({ message }); this.setState({ visible: true }); const duration = NotificationBar.configuration('duration'); setTimeout(() => this.displayNext(), duration); } render() { const position = NotificationBar.configuration('position'); const visibleClass = this.state.visible ? 'visible' : ''; return ` <div class="notification ${position} ${visibleClass}"> ${this.props.message} </div> `; } } NotificationBar.tag = 'notification-bar'; // Register the component monogatari.registerComponent(NotificationBar); ``` ## Related - [Life Cycle](/v2/building-blocks/components/life-cycle) - Component lifecycle methods - [Built-in Properties](/v2/building-blocks/components/built-in-properties) - Component properties - [Components Overview](/v2/building-blocks/components) - Creating components --- # Built-in Properties Source: https://monogatari.io/v2/building-blocks/components/built-in-properties Section: Documentation Every component has built-in properties that are used for its functionality and configuration. ## Static Properties These properties are defined on the component class itself. ### tag The HTML tag name for the component. Required. ```javascript class MyComponent extends Monogatari.Component { // ... } MyComponent.tag = 'my-component'; ``` This defines how the component is used in HTML: ```html <my-component></my-component> ``` ### _configuration Configuration object for the component. Each component should declare its own to avoid sharing state: ```javascript class MyComponent extends Monogatari.Component { static _configuration = { defaultValue: 'something', options: {} }; } ``` ### _experimental Marks the component as experimental (not stable for production): ```javascript class MyComponent extends Monogatari.Component { static _experimental = true; } ``` ### _priority Determines the order in which components are initialized: ```javascript class MyComponent extends Monogatari.Component { static _priority = 10; // Higher priority = initialized first } ``` ### engine Reference to the Monogatari engine (set automatically on registration): ```javascript static async setup() { // Access engine through static property this.engine.state({ myValue: true }); } ``` ## Instance Properties These properties are available on each component instance. ### props Component properties passed from outside: ```javascript // Set props myComponent.setProps({ title: 'Hello', visible: true }); // Access props console.log(this.props.title); // 'Hello' ``` ### state Internal component state: ```javascript // Set state this.setState({ count: 0 }); // Access state console.log(this.state.count); // 0 ``` ### engine Instance-level reference to the Monogatari engine: ```javascript render() { const label = this.engine.state('label'); return `<div>Current label: ${label}</div>`; } ``` ### _parent Reference to the parent component (if any): ```javascript // Set parent this.parent(parentComponent); // Get parent const parent = this.parent(); ``` ## Props vs State | Feature | Props | State | | :--- | :--- | :--- | | Source | External (from parent or engine) | Internal (component itself) | | Mutability | Should not be changed by component | Can be changed by component | | Update callback | `onPropsUpdate()` | `onStateUpdate()` | | Usage | Configuration, data from outside | UI state, internal data | ### Example ```javascript class Counter extends Monogatari.Component { constructor() { super(); this.props = { initialValue: 0, // Set from outside label: 'Count' }; this.state = { count: 0 // Managed internally }; } async connectedCallback() { await super.connectedCallback(); // Initialize state from props this.setState({ count: this.props.initialValue }); } increment() { this.setState({ count: this.state.count + 1 }); } render() { return ` <div> <span>${this.props.label}: ${this.state.count}</span> <button data-action="increment">+</button> </div> `; } } ``` ## Accessing Properties ### From Static Methods ```javascript static async setup() { // Access configuration const config = this.configuration(); // Access engine this.engine.state({ initialized: true }); } ``` ### From Instance Methods ```javascript render() { // Access props const title = this.props.title; // Access state const count = this.state.count; // Access engine const language = this.engine.preference('Language'); return `<div>${title}: ${count} (${language})</div>`; } ``` ## Related - [Life Cycle](/v2/building-blocks/components/life-cycle) - Component lifecycle methods - [Built-in Functions](/v2/building-blocks/components/built-in-functions) - Component methods - [Components Overview](/v2/building-blocks/components) - Creating components --- # Life Cycle Source: https://monogatari.io/v2/building-blocks/components/life-cycle Section: Documentation A component represents an object or content in the game such as screens, menus, and all other visual or structural elements. Components are custom HTML elements that encapsulate their own HTML, CSS, and JavaScript logic. ## Mounting Cycle The life cycle of a component follows the same mounting cycle as actions. This cycle runs once when the engine initializes. ### 1. Setup Set up everything the component needs for working: ```javascript static async setup() { // Add HTML content to the document this.engine.element().find('game-screen').append('<my-component></my-component>'); // Initialize configuration this.configuration({ defaultValue: 'something' }); } ``` ### 2. Bind Bind event listeners and perform DOM operations: ```javascript static async bind() { // Bind global event listeners document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { this.instances((instance) => instance.hide()); } }); } ``` ### 3. Init Final initialization after setup and binding: ```javascript static async init() { // Perform final operations // All components are now available } ``` ## Instance Lifecycle Individual component instances also have their own lifecycle methods. ### connectedCallback Called when the component is added to the DOM: ```javascript async connectedCallback() { // Always call super to ensure proper initialization await super.connectedCallback(); // Component is now in the DOM this.classList.add('ready'); } ``` ### render Returns the HTML content for the component: ```javascript render() { return ` <div class="container"> <h1>${this.props.title}</h1> <slot></slot> </div> `; } ``` ### onStateUpdate Called when component state changes: ```javascript async onStateUpdate(property, oldValue, newValue) { if (property === 'visible') { this.classList.toggle('hidden', !newValue); } } ``` ### onPropsUpdate Called when component props change: ```javascript async onPropsUpdate(property, oldValue, newValue) { if (property === 'title') { this.querySelector('h1').textContent = newValue; } } ``` ## Flow Control Methods Components can participate in game flow control, both at the static level (all instances) and instance level. ### Static Flow Control These methods iterate over all instances of the component: ```javascript // Called when user tries to advance static async shouldProceed(options) { const promises = []; this.instances((instance) => { promises.push(instance.shouldProceed()); }); return Promise.all(promises); } // Called after shouldProceed passes static async willProceed() { const promises = []; this.instances((instance) => { promises.push(instance.willProceed()); }); return Promise.all(promises); } // Called when user tries to go back static async shouldRollback() { const promises = []; this.instances((instance) => { promises.push(instance.shouldRollback()); }); return Promise.all(promises); } // Called after shouldRollback passes static async willRollback() { const promises = []; this.instances((instance) => { promises.push(instance.willRollback()); }); return Promise.all(promises); } ``` ### Instance Flow Control Each component instance can implement these methods: ```javascript // Check if this instance allows proceeding async shouldProceed() { if (this.isAnimating) { throw new Error('Animation in progress'); } } // Respond to game proceeding async willProceed() { this.classList.remove('active'); } // Check if this instance allows rollback async shouldRollback() { // Allow by default } // Respond to game reverting async willRollback() { this.resetState(); } ``` ## Event Methods ### onStart Called when a new game starts: ```javascript static async onStart() { // Reset all instances for new game this.instances((instance) => { instance.reset(); }); } ``` ### onLoad Called when a saved game is loaded: ```javascript static async onLoad() { // Restore component state this.instances((instance) => { instance.restoreFromSave(); }); } ``` ### onSave Called when the game is saved: ```javascript static async onSave() { // Perform any save-related operations } ``` ### onReset Called when the game ends or before loading a new game: ```javascript // Static version - iterates all instances static async onReset() { const promises = []; this.instances((instance) => { promises.push(instance.onReset()); }); await Promise.all(promises); } // Instance version async onReset() { this.state = {}; this.classList.remove('active'); } ``` ## Complete Life Cycle Diagram ```mermaid flowchart TD subgraph mount["Static Mounting Cycle — once, at engine init"] direction LR setup["setup()"] --> bind["bind()"] --> init["init()"] end subgraph create["Instance Creation Cycle — when added to the DOM"] direction LR ctor["constructor()"] --> connected["connectedCallback()"] --> render["render()"] end mount --> create subgraph updates["Runtime Updates — when state/props change"] direction TB props["setProps() → onPropsUpdate() → forceRender()"] state["setState() → onStateUpdate() → forceRender()"] end create --> updates subgraph flow["Flow Control — participates in game progression"] direction TB proceed["shouldProceed() → willProceed()"] rollback["shouldRollback() → willRollback()"] end updates --> flow ``` Independently of this flow, the engine calls the event methods at specific moments: `onStart()` when a new game begins, `onLoad()` when a save is loaded, `onSave()` when the game is saved, and `onReset()` when a game ends or before a new game loads. ## Related - [Components Overview](/v2/building-blocks/components) - Creating and registering components - [Built-in Properties](/v2/building-blocks/components/built-in-properties) - Component properties - [Built-in Functions](/v2/building-blocks/components/built-in-functions) - Component methods - [Actions](../actions/) - Creating custom script actions --- # Components Source: https://monogatari.io/v2/building-blocks/components Section: Documentation ## Overview A component is a custom, self-contained HTML element. It is defined as a JavaScript class and in that class, it contains all of its functionality and the HTML code that defines it. This enables you to The following code displays the most simple component you can create where it just renders some HTML you tell it to: ```javascript class MyCustomElement extends Monogatari.Component { render () { return `<h1>This is my component</h1>`; } } MyCustomElement.tag = 'my-custom-element'; ``` Now that we have our component class, we need to register it in Monogatari so it knows it exists: ```javascript monogatari.registerComponent (MyCustomElement); ``` And finally, just place it in our `index.html` with the tag we defined for it: ```markup <my-custom-element></my-custom-element> ``` When monogatari gets initialized, our component will be registered and its render method will be executed, making its final HTML be: ```markup <my-custom-element class="animated" data-component="my-custom-element"> <h1>This is my component</h1> </my-custom-element> ``` ## The move to components The `index.html` file changed significantly from Monogatari v1 to v2. Here's a comparison of what the HTML looks now and how it looked before: ### New HTML (v2) ```html <div id="monogatari"> <visual-novel> <language-selection-screen></language-selection-screen> <loading-screen></loading-screen> <main-screen> <main-menu></main-menu> </main-screen> <game-screen> <dialog-log></dialog-log> <text-box></text-box> <quick-menu></quick-menu> </game-screen> <gallery-screen></gallery-screen> <credits-screen></credits-screen> <load-screen></load-screen> <save-screen></save-screen> <settings-screen></settings-screen> <help-screen></help-screen> </visual-novel> </div> ``` ### Old HTML (v1) ```markup  <div data-notice="exit" class="modal"> <div class="row spaced"> <p data-string="Confirm" class="col xs12 m12 l12 xl12">Do you want to quit</p> <div class="col xs12 m12 l12 xl12"> <button data-action="quit" data-string="Quit">Quit</button> <button data-action="dismiss-notice" data-string="Cancel">Cancel</button> </div> </div> </div> <div data-notice="slot-deletion" class="modal"> <div class="row spaced"> <p data-string="SlotDeletion" class="col xs12 m12 l12 xl12">Are you sure you want to delete this slot?</p> <p class="col xs12 m12 l12 xl12"><small></small></p> <div class="col xs12 m12 l12 xl12"> <button data-action="delete-slot" data-string="Delete">Delete</button> <button data-action="dismiss-notice" data-string="Cancel">Cancel</button> </div> </div> </div> <div data-notice="slot-overwrite" class="modal"> <div class="row spaced"> <p data-string="SlotOverwrite" class="col xs12 m12 l12 xl12">Are you sure you want to overwrite this slot?</p> <input type="text" name="name" class="margin-1 col xs12 m12 l12 xl12" required> <div class="col xs12 m12 l12 xl12"> <button data-action="overwrite-slot" data-string="Delete">Overwrite</button> <button data-action="dismiss-notice" data-string="Cancel">Cancel</button> </div> </div> </div>  <section id="game" class="unselectable"> <div id="particles-js" data-ui="particles"></div> <div id="background" data-ui="background"></div> <div> <audio type="audio/mpeg" data-component="music"></audio> <audio type="audio/mpeg" data-component="voice"></audio> <audio type="audio/mpeg" data-component="sound"></audio> <div class="video-wrapper align-center vertical middle" data-component="video" data-ui="video-player"> <video type="video/mp4" data-ui="player" controls="true"></video> <button data-action="close-video" data-string="Close">Close</button> </div> <div data-component="modal" data-ui="messages" class="middle"> <div data-ui="message-content"></div> <div class="horizontal align-center" data-ui="inner-menu"> <button data-action="close" data-close="messages" data-string="Close">Close</button> </div> </div> <div data-component="modal" data-ui="input" class="middle"> <p data-ui="input-message" class="block"></p> <input type="text"> <small data-ui="warning" class="block"></small> <div> <button data-action="submit">Ok</button> </div> </div> </div> <div data-ui="choices" class="vertical align-center middle"></div> <div data-ui="text"> <img data-ui="face" alt=""> <span data-ui="who"></span> <p data-ui="say"></p> </div> <div data-ui="quick-menu" class="align-right"> <span data-action="back"><span class="fa fa-arrow-left"></span> <span data-string="Back">Back</span></span> <span data-action="distraction-free"><span class="fa fa-eye" data-action="distraction-free"></span> <span data-string="Hide" data-action="distraction-free">Hide</span></span> <span data-action="auto-play"><span class="fa fa-play-circle" data-action="auto-play"></span> <span data-string="AutoPlay" data-action="auto-play">Auto</span></span> <span data-action="open-menu" data-open="save"><span class="fa fa-save" data-action="open-menu" data-open="save"></span> <span data-string="Save" data-action="open-menu" data-open="save">Save</span></span> <span data-action="open-menu" data-open="load"><span class="fa fa-undo" data-action="open-menu" data-open="load"></span> <span data-string="Load" data-action="open-menu" data-open="load">Load</span></span> <span data-action="open-menu" data-open="settings"><span class="fa fa-gear" data-action="open-menu" data-open="settings"></span> <span data-string="Settings" data-action="open-menu" data-open="settings">Settings</span></span> <span data-action="end"><span class="fa fa-times-circle-o" data-action="end"></span> <span data-string="Quit" data-action="end">Quit</span></span> </div> </section>  <section data-menu="loading" data-background=""> <div class="middle"> <h2 data-string="Loading">Loading</h2> <progress data-ui="load-progress" value="0" max="100"></progress> <small data-string="LoadingMessage">Wait while the assets are loaded.</small> </div> </section>  <section data-menu="main" data-background=""> <audio type="audio/mpeg" data-component="ambient"></audio> <div class="vertical align-right bottom animated bounceIn" data-ui="inner-menu"> <button data-action="start" data-string="Start">Start</button> <button data-action="open-menu" data-open="load" data-string="Load">Load</button> <button data-action="open-menu" data-open="settings" data-string="Settings">Settings</button> <button data-action="open-menu" data-open="help" data-string="Help">Help</button> </div> </section>  <section data-menu="save" data-background=""> <button class="fa fa-arrow-left top left" data-action="back"></button> <div class="horizontal"> <input type="text" placeholder="Save Slot Name" data-input="slotName" required> <button data-string="Save" data-action="save">Save</button> </div> <div data-ui="slots" class="row spaced align-center"></div> </section>  <section data-menu="load" data-background=""> <button class="fa fa-arrow-left top left" data-action="back"></button> <h2 data-string="Load">Load</h2> <div data-ui="saveSlots"> <h3 data-string="LoadSlots">Saved Games</h3> <div data-ui="slots" class="row spaced align-center"></div> </div> <div data-ui="autoSaveSlots"> <h3 data-string="LoadAutoSaveSlots">Auto Saved Games</h3> <div data-ui="slots" class="row spaced align-center"></div> </div> </section>  <section data-menu="settings" data-background="" class="align-center"> <button class="fa fa-arrow-left top left" data-action="back"></button> <h2 data-string="Settings">Settings</h2> <div class="row spaced padded-1 align-center"> <div class="col xs12 s12 m6 l6 xl6 r6"> <div data-settings="audio" class="vertical align-center"> <h3 data-string="Audio">Audio</h3> <span data-string="Music">Music Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="music"> <span data-string="Sound">Sound Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="sound"> <span data-string="Voice">Voice Volume:</span> <input type="range" min="0.0" max="1.0" step="0.1" data-action="set-volume" data-target="voice"> </div> </div> <div class="col xs12 s12 m6 l6 xl6 r6"> <div data-settings="text-speed"> <h3 data-string="TextSpeed">Text Speed</h3> <input type="range" min="1" max="50" step="1" data-action="set-text-speed"> </div> <div data-settings="auto-play-speed"> <h3 data-string="AutoPlaySpeed">Auto Play Speed</h3> <input type="range" min="0" max="60" step="1" data-action="set-auto-play-speed"> </div> <div data-settings="language"> <h3 data-string="Language">Language</h3> <div class="horizontal"> <select data-action="set-language"> <option value="English">English</option> <option value="Español">Español</option> <option value="Français">Français</option> <option value="日本語">日本語</option> <option value="Nederlands">Nederlands</option> </select> <span class="fa fa-unsorted" data-select="set-language"></span> </div> </div> <div data-settings="resolution" data-platform="electron"> <h3 data-string="Resolution">Resolution</h3> <div class="horizontal"> <select data-action="set-resolution"></select> <span class="fa fa-unsorted" data-select="set-resolution"></span> </div> </div> </div> </div> </section>  <section data-menu="help" data-background=""> <button class="fa fa-arrow-left top left" data-action="back"></button> <h2 data-string="Help">Help</h2> <div class="align-left padded-1"> <p data-string="AdvanceHelp">To advance through the game, click anywhere on the game screen or press the space key.</p> <h3 data-string="QuickButtons">Quick Menu Buttons</h3> <p><span class="fa fa-arrow-left"></span> <span data-string="BackButton">Back.</span></p> <p><span class="fa fa-eye"></span> <span data-string="HideButton">Hide Text.</span></p> <p><span class="fa fa-save"></span> <span data-string="SaveButon">Open the Save Screen.</span></p> <p><span class="fa fa-undo"></span> <span data-string="LoadButton">Open the Load Screen.</span></p> <p><span class="fa fa-gear"></span> <span data-string="SettingsButton">Open the Settings Screen.</span></p> <p><span class="fa fa-times-circle-o"></span> <span data-string="QuitButton">Quit Game.</span></p> </div> </section> ``` That's a HUGE change right? Previously, all the HTML was right there in the `index.html` file and that was fine, it allowed people edit the HTML of their novel in a simple way and have a full understanding on where everything was. It also was helpful when styling because identifying all the elements and thus their selectors or even adding classes to them was a simple task. ### The problems it solved So if it was so good, why did it got changed? Well, sure, it was good but only up to a certain point. #### Engine Upgrades The main issue with having all the HTML there and allowing people to change it as they pleased was that it actually made it harder for everyone whenever a new engine version was released. New releases often change some of that HTML, either by adding elements, removing some, editing properties or element types etc. and if game developers had changed that HTML in their games, the only way to upgrade to the new engine version was to manually review the new code, compare it with what they had and perform all the required changes to cover up for the differences which many times was not an easy task. For example, when a bunch of data properties get changed, developers would have to go element by element changing the data properties manually which was a horrible experience for game developers and this was only part of the problem. Often developers had to edit the engine's core in order to make the HTML they added work with monogatari, making the JavaScript code another area where they had to manually see what changed and re-adapt everything every time an update got released. Now that components are self-contained, their HTML and styling can still be changed freely by the users but whenever an engine update gets released, upgrading to it is as super simple, just having to change the monogatari core files. Even when a component's code gets changed and requires developers to update their modifications to it, it only means they'll have to change those that they actually care about instead of having to review each one of them. #### Code Sharing and Re-usability Another important issue was that it was kind of hard to share code with others or even within different games from the same developers. Since it involved changing several files core to monogatari, the process was often complex and prone to errors. With components being self-contained, you can share it using just two files: a JavaScript file with the component class and a CSS file with its styling which people can just use in their projects by importing those files and not having to do much else. ### The problems it created This change has brought some confusion to people who expect all the HTML to be there for them to edit. It now results confusing where the code is coming from and how to update it which has caused monogatari not to be as beginner friendly as it used to be. However, I strongly believe these problems are the result of the lack of proper documentation. Components are in fact simple to use and work with, it just needs a mind shift and a proper explanation. ## Changing the contents of a component You might want to change the HTML of a component, either to add some elements for your game or because you want to change the way it looks. Every component has a render function like the one we showed in the simple example above. This function defines the default structure of any component but there are several ways to modify it. ### Appending Elements If all you want is to add some HTML element to the component, you can do so by adding your HTML in the `index.html` file as children of the component you want to edit. Let's retake our simple component example: ```javascript class MyCustomElement extends Monogatari.Component { render () { return `<h1>This is my component</h1>`; } } MyCustomElement.tag = 'my-custom-element'; ``` We already know that we need to add it in our `index.html` by placing the tags for it but notice how our tags are left empty, there's nothing inside of them. ```markup <my-custom-element></my-custom-element> ``` When it gets rendered, the component runs its render function and places the results inside of it: ```markup <my-custom-element class="animated" data-component="my-custom-element"> <h1>This is my component</h1> </my-custom-element> ``` So now, let's say we wanted to add another element to it, a subtitle right below our `h1` element we already defined. We could of course simply update our render function to include the new element: ```javascript render () { return ` <h1>This is my component</h1> <h2>This is my subtitle</h2> `; } ``` However, this time we were able to modify the render function because we had created our own component. What if we want to append some content to a component we didn't create like the ones monogatari ships with by default? Well, you can just place your contents in the `index.html` file. Instead of leaving the component tags empty, you can place any content you want there and it will get appended to the contents of your render function: ```markup <my-custom-element> <h2>This is my subtitle</h2> </my-custom-element> ``` ### Changing the Template Some times however, the changes we want to do are more complex than simply appending something to the HTML of an element. This is where the `template` method that all components have by default comes in. If you wanted to change a component, for example the game-screen element monogatari ships with, these are the steps you'd need to follow: #### 1. Identify the component's render method To modify the structure of any component, we first need to know what it looks like by default. To do so, we need to dive into the code of the component we want to change, you'll find all component's in the [monogatari source code repository](https://github.com/Monogatari/Monogatari/tree/develop/src/components). Inside the `index.js` file of every component, you'll find the class that defines it and most importantly, its render method. Let's take a look at the `game-screen` component it's render method looks something like this $It may have changed since the writing of this documentation$: ```javascript render () { return ` <div data-content="visuals"> <div id="tsparticles" data-ui="particles"></div> <div id="background" data-ui="background"></div> </div> `; } ``` #### 2. Create your template method Now that we know the contents of its render method, we can create our own template to add or modify the code as we need. In our `main.js`, we would get the component and then, use its template method, copying the contents it currently has on the `render` method: ```javascript monogatari.component ('game-screen').template (() => { return ` <div data-content="visuals"> <div id="tsparticles" data-ui="particles"></div> <div id="background" data-ui="background"></div> </div> `; }); ``` #### 3. Modify the contents to fit your needs Now that our template method is ready, we can use it to modify the component's structure by changing it any way we need to: ```javascript monogatari.component ('game-screen').template (() => { return ` <h1>My Title</h1> <div data-content="visuals"> <div id="tsparticles" data-ui="particles"></div> <div id="background" data-ui="background"></div> <div id="someCustomElement"></div> </div> `; }); ``` This will cause the component to use the template method we provided for it instead of the render method to get its contents giving us the freedom to modify the structure in a way almost as simple as if we had created the component ourselves. ### Performing DOM Operations A component in the end is just another HTML element, you can still perform operations over it using the DOM as you normally would. Let's try to replicate what we did to the game-screen component just using DOM operations. #### Vanilla JavaScript > [!WARNING] > Due to current limitations in the Pandora library used for Monogatari's components, it is not recommended to interact with the `innerHTML` property of any component as it's prone to cause the duplication of the children inside such component. The approach shown here, while more verbose, avoids this situation. ```javascript // Get the game-screen HTML element const gameScreen = document.querySelector ('game-screen'); // Create the title element const title = document.createElement ('h1'); title.innerText = 'My Title'; // Add our title gameScreen.insertBefore (title, gameScreen.childNodes[0]); // Get the visuals HTML element const visuals = document.querySelector ('game-screen [data-content="visuals"]'); // Create the custom div element const div = document.createElement ('div'); div.id = 'someCustomElement'; // Add our custom div to the visuals element visuals.appendChild (div); ``` #### Using the Component built-in DOM Operations ```javascript // Get the game-screen Artemis element const gameScreen = document.querySelector ('game-screen').element (); // Add our title gameScreen.prepend ('<h1>My Title</h1>'); // Add our custom div to the visuals element gameScreen.content ('visuals').append ('<div id="someCustomElement"></div>'); ``` #### Using Artemis The component built in operations from above actually use [Artemis](/v2/advanced-monogatari-development/core-libraries) internally, so they're equivalent to the following code: ```javascript const { $_ } = Monogatari; // Add our title $_('game-screen').prepend ('<h1>My Title</h1>'); // Add our custom div to the visuals element $_('game-screen [data-content="visuals"]').append ('<div id="someCustomElement"></div>'); ``` ## Related - [Life Cycle](/v2/building-blocks/components/life-cycle) - Component lifecycle methods - [Built-in Properties](/v2/building-blocks/components/built-in-properties) - Component properties - [Built-in Functions](/v2/building-blocks/components/built-in-functions) - Component methods - [Actions](../actions/) - Creating custom script actions --- # Life Cycle Source: https://monogatari.io/v2/building-blocks/actions/life-cycle Section: Documentation An action describes the functionality for a Monogatari statement. When Monogatari reads a part of the script (a statement), it will look for an action that matches the statement and run it. The life cycle of an action is divided in three parts: Mounting, Application, and Reverting. ## Mounting Cycle The mounting cycle runs once when the engine initializes. It has 3 steps: ### 1. Setup Here the action sets up everything it needs for working. This includes: - Registering state variables - Registering history objects - Adding HTML content to the document ```javascript static async setup(selector) { // Register a history for tracking applied actions this.engine.history('myaction'); // Register state variables this.engine.state({ myActionActive: false }); } ``` ### 2. Bind Once setup is complete, bind event listeners or perform DOM operations: ```javascript static async bind(selector) { // Bind event listeners document.addEventListener('click', this.handleClick); } ``` ### 3. Init Final initialization after setup and binding are complete: ```javascript static async init(selector) { // Perform final operations // All HTML elements are now available } ``` ## Statement Matching Before executing an action, Monogatari checks if the current statement matches. Actions must implement matching functions: ### matchString For string statements (most common). Receives the statement split into an array by spaces: ```javascript static matchString([keyword, type, ...rest]) { return keyword === 'play' && type === 'music'; } ``` ### matchObject For object/JSON statements: ```javascript static matchObject(statement) { return typeof statement.CustomAction !== 'undefined'; } ``` ## Application Cycle The Application cycle runs when an action is executed from the script. ### 1. Will Apply Called before the action is applied. Use for pre-application checks or setup: ```javascript async willApply() { // Check preconditions if (!this.isValid()) { throw new Error('Invalid action'); } } ``` If this method throws or returns a rejected promise, the action will not be applied. ### 2. Apply The core logic of the action. This is where the actual work happens: ```javascript async apply() { // Perform the action const element = document.createElement('div'); element.textContent = this.content; document.body.appendChild(element); } ``` ### 3. Did Apply Called after the action is applied. Use for cleanup, history updates, and determining if the game should advance: ```javascript async didApply(options = {}) { const { updateHistory = true, updateState = true } = options; if (updateHistory) { this.engine.history('myaction').push(this._statement); } if (updateState) { this.engine.state({ myActionActive: true }); } // Return whether to advance automatically return { advance: true // true = advance to next statement // false = wait for user interaction }; } ``` ## Revert Cycle The Revert cycle runs when the player goes back in the game. ### 1. Will Revert Called before reverting. Check if reversion is possible: ```javascript async willRevert() { if (this.engine.history('myaction').length === 0) { return Promise.reject('No history to revert'); } } ``` If this method throws or returns a rejected promise, the action will not be reverted. ### 2. Revert Undo the action's effects: ```javascript async revert() { // Remove the element we added const element = document.querySelector('.my-element'); if (element) { element.remove(); } // Restore previous state from history this.engine.history('myaction').pop(); } ``` ### 3. Did Revert Called after reverting. Cleanup and determine navigation behavior: ```javascript async didRevert() { return { advance: true, // true = continue reverting // false = stop here step: true // true = move to previous step // false = stay on current step }; } ``` ## Flow Control Methods These static methods are called by the engine to check if the game can proceed or rollback: ### shouldProceed Called when the user clicks to advance or auto-play triggers: ```javascript static async shouldProceed(options) { const { userInitiated, skip, autoPlay } = options; // Return resolved promise to allow proceeding // Throw or reject to prevent proceeding if (this.isBlocking) { throw new Error('Action is blocking'); } } ``` ### willProceed Called after `shouldProceed` passes, before advancing: ```javascript static async willProceed() { // Perform any cleanup before advancing } ``` ### shouldRollback Called when the user tries to go back: ```javascript static async shouldRollback() { // Return resolved promise to allow rollback // Throw or reject to prevent rollback } ``` ### willRollback Called after `shouldRollback` passes, before reverting: ```javascript static async willRollback() { // Prepare for rollback } ``` ## Event Methods These static methods respond to game events: ### onStart Called when the player starts a new game: ```javascript static async onStart() { // Initialize for new game this.engine.state({ myActionActive: false }); } ``` ### onLoad Called when a saved game is loaded. Restore visual/audio state: ```javascript static async onLoad() { // Restore state from saved game const state = this.engine.state('myActionActive'); if (state) { // Re-apply visual elements } } ``` ### onSave Called when the game is saved: ```javascript static async onSave(slot) { // slot.key - The storage key // slot.value - The saved data // Perform any save-related operations } ``` ### reset Called when a game ends or before loading a new game: ```javascript static async reset() { // Clean up all action-related elements document.querySelectorAll('.my-elements').forEach(el => el.remove()); // Reset state this.engine.state({ myActionActive: false }); } ``` ## Hook Methods These static methods allow intercepting action execution: ### beforeRun / afterRun Called before/after an action's application cycle: ```javascript static async beforeRun(context) { // Called before willApply/apply/didApply } static async afterRun(context) { // Called after the application cycle completes } ``` ### beforeRevert / afterRevert Called before/after an action's revert cycle: ```javascript static async beforeRevert(context) { // Called before willRevert/revert/didRevert } static async afterRevert(context) { // Called after the revert cycle completes } ``` ## Instance Methods ### interrupt Called to interrupt an ongoing action (e.g., skipping typewriter animation): ```javascript async interrupt() { // Stop ongoing animation or process this.stopAnimation(); } ``` ### Helper Methods ```javascript // Get the original statement const statement = this._statement; // Get current cycle ('Application' or 'Revert') const cycle = this._cycle; // Access extra context const extras = this._extras; // Access the engine const engine = this.engine; ``` ## Complete Life Cycle Diagram ```mermaid flowchart TD subgraph mount["Mounting Cycle — once, at engine init"] direction LR setup["setup()"] --> bind["bind()"] --> init["init()"] end mount --> match{"matchString() /<br/>matchObject()"} match -->|statement matches| ctor["constructor()"] subgraph apply["Application Cycle — statement runs"] direction TB willApply["willApply()"] --> applyStep["apply()"] --> didApply["didApply() → { advance }"] end ctor --> willApply didApply --> proceed{"shouldProceed()"} proceed -->|passes| willProceed["willProceed()"] --> next(["Next statement"]) next -.->|player rolls back| rollback{"shouldRollback()"} rollback -->|passes| willRollback["willRollback()"] subgraph revert["Revert Cycle — player goes back"] direction TB willRevert["willRevert()"] --> revertStep["revert()"] --> didRevert["didRevert() → { advance, step }"] end willRollback --> willRevert ``` Independently of this flow, the engine calls the event methods at specific moments: `onStart()` when a new game begins, `onLoad()` when a save is loaded, `onSave()` when the game is saved, and `reset()` when a game ends or before a new game loads. ## Related - [Actions Overview](/v2/building-blocks/actions) - Creating and registering actions - [Components](../components/) - Creating custom UI components --- # Actions Source: https://monogatari.io/v2/building-blocks/actions Section: Documentation ## Overview Actions are what defines what any given statement in a script should do. When Monogatari reads a part of the script (a statement), it looks for an action that matches the statement and runs it. ## Creating a Custom Action The following code displays a simple example of an action that does something when applied (advancing through the game) and something else when reverted (rolling back through the game): ```javascript class MyAction extends Monogatari.Action { // Unique identifier for this action static id = 'MyAction'; // Match statements starting with 'myaction' static matchString([action]) { return action === 'myaction'; } constructor([myaction, ...args]) { super(); this.args = args; } apply() { // Do something when the action is executed console.log('Action applied with args:', this.args); return Promise.resolve(); } didApply() { // Return whether to advance automatically return Promise.resolve({ advance: true }); } revert() { // Undo the action when rolling back console.log('Action reverted'); return Promise.resolve(); } didRevert() { return Promise.resolve({ advance: true, step: true }); } } ``` This action will match statements like: ```javascript 'myaction' 'myaction something' 'myaction one two three' ``` ## Registering an Action Once you have your action class, register it with Monogatari: ```javascript monogatari.registerAction(MyAction); ``` ## Static Properties | Property | Type | Description | | :--- | :--- | :--- | | `id` | `string` | Unique identifier for the action (required) | | `_experimental` | `boolean` | Marks the action as experimental (default: `false`) | | `_configuration` | `object` | Action-specific configuration storage | | `loadingOrder` | `number` | Order for loading actions (default: `0`). Higher values load first. | | `engine` | `Monogatari` | Reference to the Monogatari engine (set automatically) | ## Instance Properties | Property | Type | Description | | :--- | :--- | :--- | | `_statement` | `string\|object` | The original statement that matched this action | | `_cycle` | `string` | Current cycle: `'Application'` or `'Revert'` | | `_extras` | `object` | Additional context passed to the action | | `engine` | `Monogatari` | Reference to the Monogatari engine | ## Matching Methods Actions must implement at least one matching method to identify which statements they handle. ### matchString For string-based statements (most common): ```javascript static matchString([keyword, ...args]) { return keyword === 'myaction'; } ``` The statement is passed as an array of words split by spaces. ### matchObject For object-based statements (JSON): ```javascript static matchObject(statement) { return typeof statement.MyAction !== 'undefined'; } ``` ## Configuration Actions can store and retrieve configuration: ```javascript // Set configuration MyAction.configuration({ defaultValue: 'something', options: { enabled: true } }); // Get all configuration const config = MyAction.configuration(); // Get specific property const value = MyAction.configuration('defaultValue'); ``` ## Complete Example Here's a more complete example of a custom action: ```javascript class NotifyAction extends Monogatari.Action { static id = 'Notify'; static _configuration = { duration: 3000 }; // Setup runs once when the engine initializes static async setup() { // Initialize any state or history needed this.engine.history('notifications'); } static matchString([action]) { return action === 'notify'; } constructor([notify, ...message]) { super(); this.message = message.join(' '); } async apply() { // Show notification const duration = NotifyAction.configuration('duration'); // Create and show notification element const notification = document.createElement('div'); notification.className = 'custom-notification'; notification.textContent = this.message; document.body.appendChild(notification); // Auto-remove after duration setTimeout(() => notification.remove(), duration); } async didApply() { // Save to history for rollback support this.engine.history('notifications').push(this.message); return { advance: true }; } async revert() { // Remove from history this.engine.history('notifications').pop(); } async didRevert() { return { advance: true, step: true }; } } // Register the action monogatari.registerAction(NotifyAction); ``` Usage in script: ```javascript monogatari.script({ 'Start': [ 'notify Welcome to the game!', 'notify This message will appear as a notification.', // ... rest of script ] }); ``` ## Related - [Life Cycle](/v2/building-blocks/actions/life-cycle) - Detailed explanation of action lifecycle methods - [Components](../components/) - Creating custom UI components --- # Variables & Data Storage Source: https://monogatari.io/v2/building-blocks/data-storage Section: Documentation ## Overview Chances are you'll eventually want to save some information about the player. It may be a name, some stats, the amount of in-game currency the player has or any other sort of variable you use in your game and want to persist every time the player saves the game. Monogatari has a built-in storage object where you can and should place all the variables you'll use and want to save. There's already a declaration made for you in the `storage.js` file. We recommend you keep your storage in that file since it's easier to keep track of all your variables and also means you only have to update that one when you add, remove or update any of them. By default, the storage looks something like this: ```javascript monogatari.storage ({ player: { name: '' } }); ``` ## Adding more variables The storage is a simple JSON object, meaning we can add as much variables as we want. Let's say we wanted to save the player's age, an important flag for our game and also some stats. We can add some new properties to our storage: ```javascript monogatari.storage ({ player: { name: '', age: 0 }, myFlag: false, stats: { hp: 100, mp: 100, inventory: { gold: 1000, iron: 10 } } }); ``` Notice that the values we provide in this initial declaration will be the default values for these variables. ## Updating a value When something happens in our game and we want to update the value for one of our variables in our storage, we can use the same storage function to do so. Let's say we want to update the player's age: ```javascript monogatari.storage ({ player: { age: 18 } }); ``` Calling the storage function and providing a new object will not replace the initial one. It will instead take the values we provide and update the storage for us. We can of course update multiple variables in a single call: ```javascript monogatari.storage ({ player: { age: 18 }, myFlag: true, stats: { hp: 80 } }); ``` It is also possible to update a variable by doing a direct assignment: ```javascript monogatari.storage ().player.age = 18; ``` ## Retrieving a variable's value Retrieving the value of a variable once again involves the storage function. Let's say we wanted to retrieve the player's name. All of the following options are valid ways to do so: ```javascript // Providing the property we want to access const { name } = monogatari.storage ('player'); const name = monogatari.storage ('player').name; // Not providing any property const { player: { name } } = monogatari.storage (); const name = monogatari.storage ().player.name; ``` As you can see from that example, it is possible to send the storage function a string, in this case `player` and it will return us that specific variable which can save us some code. Because of this feature, retrieving a non-nested variable like the `myFlag` one can be done in these ways: ```javascript // Providing the property we want to access const flag = monogatari.storage ('myFlag'); // Not providing any property const { myFlag } = monogatari.storage (); const flag = monogatari.storage ().myFlag; ``` ### The retrieve, transform and update pattern Some times, we want to update a variable in a way that the new value is the result of performing an operation over the current value. For example, let's say we wanted to add or substract 20 hp points from the player's stats. ```javascript // First, we have to retrieve the current value // for the hp variable const { hp } = monogatari.storage ('stats'); // Now, we can either substract or add those 20 points. const newHP = hp + 20; // Finally, we can perform the update monogatari.storage ({ stats: { hp: newHP } }); ``` For simple transformations as this one, we can actually perform the transformation and update in a single step: ```javascript // First, we have to retrieve the current value // for the hp variable const { hp } = monogatari.storage ('stats'); // We add the 20 points and update the value // in a single step monogatari.storage ({ stats: { hp: hp + 20 } }); ``` ## Data Interpolation It is possible that we'll want to use the variables in the storage inside a dialog or even in a character's name. Monogatari features some custom string interpolation which you can use by writing a storage variable's key or name inside of two curly braces. Let's say you wanted to use the player's name and age in a dialog. Here's what our statement would look like: ```javascript 'Hi {{player.name}}! I can see you\'re {{player.age}} years old.' ``` Notice how you're able to interpolate variables even if they're nested as the player variables are. ## Mixing it together Monogatari has a lot of actions that will let you take advantage of the storage, from inputs and custom functions to dialogs and nice tricks with interpolations. Here's an example of a script using the storage on different actions. ```javascript monogatari.script ({ 'Start': [ {'Input': { 'Text': 'What is your name?', 'Validation': (input) => { return input.trim().length > 0; }, 'Save': (input) => { monogatari.storage ({ player: { name: input, age: 18 } }); }, 'Revert': () => { monogatari.storage ({ player: { name: '', age: 0 } }); } }}, 'Your name is {{player.name}}', {'Function':{ 'Apply': () => { // We'll overwrite the player's name but save the old one in a new // value so that we can roll back and restore it if needed. const { name } = monogatari.storage ('player'); const { hp, inventory: { gold } } = monogatari.storage ('stats'); monogatari.storage ({ player: { name: 'Georg', }, oldName: name, stats: { hp: hp - 50, inventory: { gold: gold + 250 } } }); }, 'Revert': () => { // When rolling back, we'll restore the name to what it was before. const oldName = monogatari.storage ('oldName'); const { hp, inventory: { gold } } = monogatari.storage ('stats'); monogatari.storage ({ player: { name: oldName, }, stats: { hp: hp + 50, inventory: { gold: gold - 250 } } }); } }}, '{{player.name}} is {{player.age}} years old.', '{{stats.mp}} costs the ability "Fire Storm".', '{{stats.inventory.gold}}g is in his bag of gold.', 'end' ] }); ``` ## Where to go next Storage is most useful alongside the actions that read and change it: - [Conditionals](/v2/script-actions/conditionals) — branch your story on stored values (affection points, flags, choices made). - [Functions](/v2/script-actions/javascript) — run JavaScript to compute and update storage. - [Input](/v2/script-actions/input) — save what the player types (like their name) straight into storage. --- # Characters > Learn about characters, their properties and how to create them! Source: https://monogatari.io/v2/building-blocks/characters Section: Documentation ## Overview Characters are probably one of the most important parts of your novel, not only used for displaying them as sprites but also to display their dialogs. ## Properties The following table lists all the properties you can set for each character. | Name | Type | Optional | Description | | :--- | :--- | :--- | :--- | | `name` | `string` | Yes | The name that will be shown when this character speaks. Supports storage and translation interpolations. | | `color` | `string` | Yes | A valid [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color) which will be used to color the character's name. | | `directory` | `string` | Yes | Specifies the sub-directory where the sprites and expressions images for the character are stored in case they are not in the root `assets/characters` directory. | | `sprites` | `object` | Yes | An object with the identifiers and file names for each [sprite](/v2/script-actions/characters) available for the character. | | `default_expression` | `string` | Yes | Identifier of the expression to show every time the character speaks (must be defined in `expressions`). | | `expressions` | `object` | Yes | An object with the identifiers and file names for each [side expression](/v2/script-actions/dialogs#side-images) available for the character. | | `nvl` | `boolean` | Yes | Default is `false`. Whether the character's dialogs should be shown in [NVL mode](/v2/script-actions/dialogs#nvl-dialogs). | | `type_animation` | `boolean` | Yes | Default is `true`. Whether the typewriter animation should be used when the character speaks. | | `layers` | `array` | Yes | Experimental. Defines the order of layers from back to front for layered sprites. | | `layer_assets` | `object` | Yes | Experimental. Maps layer names to their available sprite options for layered sprites. | ## Declaration Declaring characters is really simple. First, you need to define an identifier. This is what you'll use for the [`dialog`](/v2/script-actions/dialogs) and [`show character`](/v2/script-actions/characters) actions. We'll choose the identifier `y`, short for Yui in this tutorial. ```javascript monogatari.characters ({ 'y': { } }); ``` Do you have more than one character? No problem! You can define as many characters as you want, just make sure that each character has a unique identifier. ```javascript monogatari.characters ({ 'y': { }, 'm': { } }); ``` We've come up with our identifiers and they point to an empty object. Inside this object is where we'll define each of the properties we need for each character. ## Name and Color The most basic properties are the name and color for our characters. The name will appear in the textbox every time the character speaks and the color specifies what color that name will be. ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff' } }); ``` ## Character Sprites Since we are building visual novels, chances are we also need images for our characters. All your character's sprites should be placed in your `assets/characters` directory, let's see what that looks like. ### 1. Enter the `assets` directory ![](https://cdn.restlessdreams.cloud/84f5f859-7a6a-4f82-ac2f-c4484211094d.webp) ### 2. Enter the `characters` directory ![](https://cdn.restlessdreams.cloud/173d1b8e-c212-4e58-903e-d6325d0cf21e.webp) ### 3. Place all your sprite images ![](https://cdn.restlessdreams.cloud/b9ef2025-df60-47d0-8a00-d597df76ee37.webp) ### 4. Declare your assets Now that we have all our sprites in our assets directory, we need to declare them so monogatari knows about them. To do so, we'll use the `sprites` property of our character: ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' } } }); ``` Notice how for each sprite we assigned two things: 1. A key or identifier which is the way we'll refer to that specific sprite. 2. The name of the file. ```javascript identifier: 'file.name' ``` Both items are independent of each other so while in the last example we used identifiers similar to the file names, we could have chosen any identifier, the following would be perfectly valid for example: ```javascript someKey: 'normal.png' happy: 'my_file_name.png' ``` To learn how to show a character sprite, see the [Show Character action](/v2/script-actions/characters). ## Custom Sub-directory In the [Character Sprites](/v2/building-blocks/characters#character-sprites) section we added all of our character sprite images into the `assets/characters` directory. This approach is pretty straight forward but can become a bit troublesome as you add more characters. For starters, the directory could start feeling cluttered and you would not be able to use the same name on different files without them getting overwritten. A solution for this issue is to have a different directory for each character where we'll place all the assets for that character alone. This is achieved by specifying the `directory` property in your character declaration. This property expects the name of a sub-directory inside the `assets/characters` directory. For example, if you create a sub-directory `assets/characters/my-character` then you should set the `directory` property to `'my-character'`. Let's take a look at the whole process: ### 1. Create your sub-directory ![](https://cdn.restlessdreams.cloud/24638477-3ddf-41aa-8ef5-2264ffe73373.webp) ### 2. Place all your character assets in that sub-directory ![](https://cdn.restlessdreams.cloud/f2e86fe5-e847-4684-a628-4fca6c20f070.webp) ### 3. Set the directory property in your declaration Now that we've created the sub-directory and placed all our assets for a specific character in it, then we must specify the `directory` property in our character so monogatari knows where the files are located. ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' } } }); ``` ## Expressions / Side Images It is also possible to define side images or expressions to show on the textbox when your character speaks. ### 1. Add your expression images to your assets For this example we'll add all our expressions in their own directory. This is not required though and you can place them right where your character's sprites are. ![](https://cdn.restlessdreams.cloud/02078153-e12d-4178-a5b7-e93e27db8a34.webp) Now that we've created our `expressions` sub-directory, we'll place all our expression images in it. ![](https://cdn.restlessdreams.cloud/31fad803-b46c-4a22-9927-1f47aa9097da.webp) ### 2. Add the expressions to your declaration Now that we've added our files, we need to define them in our character declaration by defining the `expressions` property. Just like the `sprites` property, it expects an identifier/filename list. ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' }, expressions: { angry: 'expressions/normal.png', happy: 'expressions/happy.png', normal: 'expressions/normal.png', sad: 'expressions/sad.png', surprised: 'expressions/surprised.png' } } }); ``` Notice how we added the `expressions/` prefix to all of the file names to account for the `expressions` directory we put the files in. If we hadn't done that and we had placed them right with our sprites, the prefix would not be needed but we would have to change the names of the files so that they don't overlap with the sprites ones. To learn how to show these expressions in a dialog, see the [Dialog action](/v2/script-actions/dialogs). ## Default Expression It is also possible to define a default side image / expression for your character. This default one will be shown for all of your character's dialogs that do not specify any other expression. The `default_expression` property expects the identifier of one of your expressions as its value. Previously we defined the `normal` expression for our character: ```javascript normal: 'expressions/normal.png' ``` If we wanted to make that one the default expression, then we'd need to set the `default_expression` property to `normal`: ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' }, expressions: { angry: 'expressions/normal.png', happy: 'expressions/happy.png', normal: 'expressions/normal.png', sad: 'expressions/sad.png', surprised: 'expressions/surprised.png' }, default_expression: 'normal' } }); ``` ## NVL Mode By default, characters will speak in `adv` mode. In ADV mode, the textbox appears in the bottom of the screen and only displays a dialog at a time. NVL mode will make the textbox cover the whole screen and will display several dialogs in a log format. The `nvl` property accepts a boolean value $`true` or `false`$ and is set to `false` by default. Setting it to `true` will make all of the character's dialogs to be shown in `nvl` mode. ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' }, expressions: { angry: 'expressions/normal.png', happy: 'expressions/happy.png', normal: 'expressions/normal.png', sad: 'expressions/sad.png', surprised: 'expressions/surprised.png' }, default_expression: 'normal', nvl: true } }); ``` If you want to learn more about the different dialog modes, check the [Dialog action](/v2/script-actions/dialogs) and the [Text Box component](/v2/components/text-box). ## Typewrite Animation Monogatari allows you to disable the typewrite animation for your game from your game's settings, however, some times you only want to disable the animation for a specific character. The `type_animation` property accepts a boolean value $`true` or `false`$ and is set to `true` by default. Setting it to `false` will disable the animation for all of that character's dialogs. ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { angry: 'normal.png', happy: 'happy.png', normal: 'normal.png', sad: 'sad.png', surprised: 'surprised.png' }, expressions: { angry: 'expressions/normal.png', happy: 'expressions/happy.png', normal: 'expressions/normal.png', sad: 'expressions/sad.png', surprised: 'expressions/surprised.png' }, default_expression: 'normal', nvl: true, type_animation: false } }); ``` ## Experimental: Layered Sprites > [!WARNING] > This feature requires `ExperimentalFeatures` to be enabled in your game settings. For paper-doll style characters where you want to independently control different parts (like outfits, expressions, or accessories), you can use layered sprites. ### Additional Properties for Layers | Name | Type | Description | | :--- | :--- | :--- | | `layers` | `array` | Defines the order of layers from back to front (determines z-index) | | `layer_assets` | `object` | Maps layer names to their available sprite options | ### Layer Declaration ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', // Define layer order (back to front) layers: ['base', 'clothes', 'face', 'accessories'], // Define sprites for each layer layer_assets: { base: { body: 'base_body.png' }, clothes: { uniform: 'clothes_uniform.png', casual: 'clothes_casual.png', swimsuit: 'clothes_swimsuit.png' }, face: { neutral: 'face_neutral.png', happy: 'face_happy.png', sad: 'face_sad.png', angry: 'face_angry.png' }, accessories: { none: '', glasses: 'acc_glasses.png', hat: 'acc_hat.png' } }, // You can still define standard sprites as fallbacks sprites: { normal: 'normal.png' } } }); ``` For information on how to control individual layers in your script, see the [Character Layers action](/v2/script-actions/character-layers). ## A complete character Putting it together, here's a full character you can drop into your `js/script.js` and adapt — a name and color, a sprite directory, several sprites and expressions, and a default expression: ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#00bfff', directory: 'yui', sprites: { normal: 'normal.png', happy: 'happy.png', sad: 'sad.png', surprised: 'surprised.png' }, expressions: { normal: 'expressions/normal.png', happy: 'expressions/happy.png', sad: 'expressions/sad.png' }, default_expression: 'normal' } }); ``` With that defined, `y` can speak, change sprite, and show a side expression: ```javascript monogatari.script ({ 'Start': [ 'show character y happy at center with fadeIn', 'y:happy Hi! I\'m Yui — nice to meet you!', 'y:sad ...but I have to go now.', 'hide character y with fadeOut', 'end' ] }); ``` Next, learn how to show and animate characters in the [Show Character](/v2/script-actions/characters) action. --- # Script & Labels Source: https://monogatari.io/v2/building-blocks/script-and-labels Section: Documentation ## Overview The script is the soul and body of your game, it is the place where you define everything that happens on it. It is made out of labels that are just like the chapters of a book and inside of each label, you have a list of statements that will be run one by one as your story unfolds. ## Script A monogatari script is nothing more than a [JSON object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON). In simple terms, a JSON object is defined with two curly braces `{}`. Inside these curly braces, you can have a list of named properties that point to a value. For example, if we wanted to define a person using the JSON notation, we could do something like this: ```javascript const person = { 'name': 'Jane Doe', 'age': 24 }; ``` This is what we call key/value pairs, where a key like `name` or `age` points to a value like `Jane Doe` or `24`. Notice how each key/value pair has a comma in the end separating it from the next one. Missing commas is the \#1 issue that people have on their scripts. In Monogatari's case, your script is a list of keys $the names of the [labels](/v2/building-blocks/script-and-labels#labels) on your game$ and values $the list of statements these labels are made of$. For example: ```javascript { 'Start': [ 'Hi there!', 'This is a list of statements', 'jump myLabel' ], 'myLabel': [ 'And this is yet another label', 'Also a list of statements', 'end' ] } ``` Now, while that object does defines a monogatari script, just by itself it doesn't do anything. You must use the script function to let monogatari know what's your script: ```javascript monogatari.script ({ 'Start': [ 'Hi there!', 'This is a list of statements', 'jump myLabel' ], 'myLabel': [ 'And this is yet another label', 'Also a list of statements', 'end' ] }); ``` By default, the `script.js` file contains the initial script for any monogatari game and you can build your game from there by adding more content and removing the old one. ## Labels Let's take a look at an incredibly simple script, this is the most basic script a game could have: ```javascript monogatari.script ({ 'Start': [ 'This is a statement.', 'end' ] }); ``` Notice that `Start` string. By default, `Start` is the first label that Monogatari will play when a game starts. As you can see, this label is pointing to a list of statements that monogatari will run one by one. In programming terms, a label is like a function or subroutine: a named list of statements you can run, and that you can jump to from anywhere in your game. As we said before, labels are just like the chapters of a book, but they also give you a logical way to divide your game. ### Jumping between labels As books can have many chapters, you can have many labels as well! Not only that, you can make your game move from one label to another using the [Jump action](/v2/script-actions/jump). ```javascript monogatari.script ({ 'Start':[ 'This is a statement.', 'jump mylabel' ], 'mylabel':[ 'This is another statement.', 'Pretty easy huh?', 'end' ] }); ``` As you can see from this script, we have two labels, `Start` and `mylabel.` Players will start in the `Start` one by default which will print out the first dialog and when the player clicks to advance, it will reach the `jump mylabel` statement. When reached, the game will simply carry on with the statements inside the `mylabel` label without the player ever noticing something happened. ## Translating your Script Making your game available in many languages is super simple, head over to the Internationalization guide to learn more. ## Splitting your script in multiple files As your game script grows, having it all in the same file might become troublesome. Splitting your script into multiple files is a good way to get organized and make it less cluttered. Learn how to do this in the [Split Files](/v2/configuration-options/split) section. ## Related - [Dialogs](/v2/script-actions/dialogs) - Writing dialog text - [Jump](/v2/script-actions/jump) - Navigating between labels - [Variables & Data Storage](/v2/building-blocks/data-storage) - Storing game data - [Internationalization](/v2/configuration-options/game-configuration/internationalization) - Multi-language support --- # Building Blocks Source: https://monogatari.io/v2/building-blocks Section: Documentation Guides in this section: - [Script & Labels](/v2/building-blocks/script-and-labels) - [Characters](/v2/building-blocks/characters) - [Variables & Data Storage](/v2/building-blocks/data-storage) - [Actions](/v2/building-blocks/actions) — The statements that make up your script and how to build custom ones. - [Components](/v2/building-blocks/components) — The HTML elements (screens, menus, UI) that make up the interface. --- # Diagnosing Errors Source: https://monogatari.io/v2/diagnosing-errors Section: Documentation ## The Browser Developer Tools The browser's developer tools are your best friend. Learning your way around them will make wonders for you. Here are a few resources you might find useful: * [What are browser developer tools?](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools) * [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/) Most importantly when dealing with errors on your novel, the console included on those dev tools is essential. To open your browser dev tools, you can press `Ctrl + Shift + i` or `Command + Shift + i` if you're on a mac. Alternatively, you can right click on the page and choose the `Inspect element` option. Once the dev tools pop open, select the `Console` tab to see the logs printed by your game. ## Tips for asking for help We all need some help every once in a while, here is a list of things that will make the experience of asking for help better for everyone and more useful to you! ### Provide as much detail as you can When asking for help, please provide ALL the necessary information, more often than not you will be asked "what version are you using?" and "please show me your code" when you don't provide that information from the beginning. #### When dealing with errors: 1. Provide what monogatari version you're using 2. Provide what browser you're using 3. Provide the full error message you're getting, whether from Monogatari or from your browser's console 4. Provide the piece of code / script causing the issue and the surrounding code $at least 5 lines before and after$ #### When dealing with unexpected behaviors 1. Provide what monogatari version you're using 2. Provide what browser you're using 3. Provide the piece of code / script that's not behaving as you expected and the surrounding code $at least 5 lines before and after$ 4. Provide a description of what you are attempting to do and what is happening ### Ensure your code is properly indented If you're sharing code, ensuring it's properly indented will help a lot for the people who's trying to help you out as it will be easier to read and easier to catch what's going on. #### Badly Indented Code ```javascript monogatari.script ({ // The game starts here. 'Start': [ 'show scene #f7f6f6 with fadeIn', 'show notification Welcome', { 'Input': { 'Text': 'What is your name?', 'Validation': function (input) { return input.trim ().length > 0; }, 'Save': function (input) { this.storage ({ player: { name: input}}); return true; }, 'Revert': function () { this.storage ({ player: { name: '' } });}, 'Warning': 'You must enter a name!' } }, 'y Hi {{player.name}} Welcome to Monogatari!', { 'Choice': { 'Dialog': 'y Have you already read some documentation?', 'Yes': { 'Text': 'Yes', 'Do': 'jump Yes' }, 'No': { 'Text': 'No', 'Do': 'jump No' } } } ] }); ``` #### Perfectly Indented Code ```javascript monogatari.script ({ // The game starts here. 'Start': [ 'show scene #f7f6f6 with fadeIn', 'show notification Welcome', { 'Input': { 'Text': 'What is your name?', 'Validation': function (input) { return input.trim ().length > 0; }, 'Save': function (input) { this.storage ({ player: { name: input } }); return true; }, 'Revert': function () { this.storage ({ player: { name: '' } }); }, 'Warning': 'You must enter a name!' } }, 'y Hi {{player.name}} Welcome to Monogatari!', { 'Choice': { 'Dialog': 'y Have you already read some documentation?', 'Yes': { 'Text': 'Yes', 'Do': 'jump Yes' }, 'No': { 'Text': 'No', 'Do': 'jump No' } } } ] }); ``` ## Generic errors ![](https://cdn.restlessdreams.cloud/b0eb0ba9-674a-4c39-8a28-f548e459c46c.webp) When an error unknown to monogatari occurs, you'll get a similar screen to this one. This usually means you have an error on your script. More information about the error like the file and line the error is in will be available in your browser's console. The exact error message varies from browser to browser. This specific example of an error was caused by the following script: ![](https://cdn.restlessdreams.cloud/0be49286-c602-496b-90df-5e1178563839.webp) Paying some attention to it might reveal there's a missing comma after the `show scene` statement. Going to the browser's console, allowed us to see more information about it. This is what Firefox showed: ![](https://cdn.restlessdreams.cloud/80664b70-0b83-4232-8983-043610ac2d73.webp) Chrome on the other hand, showed an error a little bit more generic: ![](https://cdn.restlessdreams.cloud/abe86b3d-2e0c-4119-ae7a-fd72a3eb7c12.webp) They both however, referred to the same line as causing the issue, shown at the end of the error as `script.js:164`. Our code editor also showed there was an error there, highlighting that same line in red: ![](https://cdn.restlessdreams.cloud/0be49286-c602-496b-90df-5e1178563839.webp) So, even if the errors don't exactly scream "You're missing a comma!" back to you, they at least let you know around what line you're having an issue. Paying closer attention to that area will most likely lead you to finding what's the actual error. Other errors have much more specific error messages that will let you know what's the error right away but this one is a good example since it's very common and the messages provided by browsers are not perfect. ### Game Apparently Stuck If it appears the game is stuck and won't advance anymore no matter how much you click, chances are an error occurred. Check your browser's console to see what's going on. If no information is visible, then try enabling the debug mode. ## Using the Debug Mode Monogatari has a lot of debug logs that are disabled by default. You can enable them by adding this piece of code to your `main.js` file, right before the `monogatari.init ()` function. ```javascript monogatari.debug.level (5); ``` Once added, reload the page and open the browser's console, you should see a whole bunch of new things being logged now. ### Debug levels The number you pass to `monogatari.debug.level ()` sets how much gets logged. Each level includes everything from the lower levels, so higher numbers are noisier: | Level | Name | What gets logged | | :--- | :--- | :--- | | `0` | None | Nothing. Logging is off. | | `1` | Error | Errors only. | | `2` | Warning | Errors and warnings. | | `3` | Info | The above plus informational messages. | | `4` | Debug | The above plus detailed debug logs (the engine's internal step-by-step logging). | | `5` | All | Everything. | For diagnosing a stuck game, `5` is the most useful since it shows the engine's full play-by-play. > [!NOTE] > These debug logs come from a separate debug build of the engine. If you're not > using that build, `monogatari.debug` calls are simply ignored and changing the > level will have no visible effect. ## Common Errors ### Missing Commas After every statement of your script, there must be a comma unless it is the last statement in the label: ```javascript monogatari.script ({ 'Start': [ 'show scene #f7f6f6 with fadeIn', // This comma right here 'Hi!', // This comma right here 'end' ] }); ``` A comma must be used to separate different labels in a script: ```javascript monogatari.script ({ 'Start': [ 'show scene #f7f6f6 with fadeIn', 'Hi!', 'jump myLabel' ], // This comma right here 'myLabel': [ 'How are you?', 'end' ] }); ``` ### Incorrectly Closed Labels or Scripts A script is a JSON object, it must start with a curly brace $`{`$ and end with one as well $`}`$ Labels are arrays and as such, they must start with a square bracket $`[`$ and end with one $`]`$ --- # F.A.Q. Source: https://monogatari.io/v2/f-a-q Section: Documentation ## Is it free? Yes ## Can I use it commercially? Yes, you can use it for commercial and non-commercial games completely free! ## Is it really a game engine? Short Answer: For common purposes, sure, you can think of Monogatari as a visual novel engine Technical Answer: Monogatari is a web development framework created to build modern websites that just happen to be games, it lacks quite a lot of elements to be considered a real game engine as it is only using an already available platform: your browser. ## Who develops Monogatari? A lot of awesome people help developing Monogatari, you can view the whole list here: [https://monogatari.io/contributors](https://monogatari.io/contributors) --- # Upgrading from v1.4.1 > Learn all you need to know about upgrading your game! Source: https://monogatari.io/v2/upgrading-from-v1-4-1 Section: Documentation Monogatari has been completely rewritten and many things have changed, however, the script syntax and overall functionality has stayed almost the same so porting your game from v1.4.1 to the newest version is not that complicated! ## 1. Moving your files Lets start with the easiest task, the best way to port your game is starting fresh and that means downloading the newest version available and move your files there, step by step instead of trying to update your old project. ### Assets Lets start with the assets, they are now saved on a directory called assets. Here is an equivalence of where you used to store your assets before and where you should store them now: | Asset | Old Directory | New Directory | | :--- | :--- | :--- | | Music | `audio/music/` | `assets/music/` | | Voice | `audio/voice/` | `assets/voices/` | | Sounds | `audio/sound/` | `assets/sounds/` | | Characters | `img/characters` | `assets/characters/` | | Backgrounds / Scenes | `img/scenes/` | `assets/scenes/` | | UI Assets | `img/ui/` | `assets/ui/` | | Video | `video` | `assets/videos/` | Why did this changed you may ask. Well, by creating an universal assets directory, it is easier to both keep your assets out of version control systems $git and others$ and also, it allows you to host your assets remotely in an easier way. More info on this will be made available later on. ## 2. Storage Your players most likely have lots of save files and we want them to keep them even though we're updating the engine. By default, the new version handles storage in a different way which will result on the save files not showing up. To allow your players to keep their save files, we need to change this. 1. Go over to the `options.js` file 2. Find the `Storage` configuration almost at the bottom of the file 3. Edit the `Adapter` property and set it to an empty string $`''`$ 4. Edit the `Store` property and set it to an empty string $`''`$ ### Copy your storage object Now its time to copy your storage object. The `js/storage.js` file is still the place where you'll put all the items you want to save on your game, the syntax has changed just a bit. Storage on v1.4.1 storage.js ```javascript let storage = { player: { name: "" } }; ``` Storage on v2.0.0 storage.js ```javascript monogatari.storage ({ player: { name: '' } }); ``` As you can see, it really is just a matter of changing the `let storage = { ...storage };` format to the new `monogatari.storage ({ ...storage });` format, you can copy your storage object exactly as it is! ### Update the syntax to set / get values from the storage Previously, when you wanted to modify the storage, you would modify the variable directly like this: script.js ```javascript storage.someVariable = someValue; ``` Modifying the storage like that is no longer possible since it has been moved to a function. While you can look at all the new syntax on the [storage documentation](/v2/building-blocks/data-storage), the easiest way to update the syntax is by replacing all occurrences of it you have on your script for something like this: ```javascript monogatari.storage ().someVariable = someValue; ``` ## 3. Assets Declarations Just like with the storage, assets declaration syntax has changed just a bit, here's a small comparative on how the assets declaration looks like on your `script.js` file on both the old and the new version. Assets declaration on v1.4.1 script.js ```javascript // Define the Particles JS Configurations used in the game let particles = { }; // Define the music used in the game. const music = { }; // Define the voice files used in the game. const voice = { }; // Define the sounds used in the game. const sound = { }; // Define the videos used in the game. const videos = { }; // Define the images used in the game. const images = { }; // Define the backgrounds for each scene. const scenes = { }; ``` Assets declaration on v2.0.0 script.js ```javascript // Define the Particles JS Configurations used in the game monogatari.action ('particles').particles ({ }); // Define the music used in the game. monogatari.assets ('music', { }); // Define the voice files used in the game. monogatari.assets ('voices', { }); // Define the sounds used in the game. monogatari.assets ('sounds', { }); // Define the videos used in the game. monogatari.assets ('videos', { }); // Define the images used in the game. monogatari.assets ('images', { }); // Define the backgrounds for each scene. monogatari.assets ('scenes', { }); ``` ## 4. Script and Labels Declarations Just as with the storage and assets, the way to declare the script for your game has changed its syntax, here's a comparison on the old and new way: Script declaration on v1.4.1 ```javascript let script = { // The game starts here. "Start": [ "notify Welcome", { "Input": { "Text": "What is your name?", "Validation": function (input) { return input.trim().length > 0; }, "Save": function (input) { storage.player.Name = input; return true; }, "Warning": "You must enter a name!" } }, "h Hi {{player.Name}} Welcome to Monogatari!", { "Choice": { "Dialog": "h Have you already read some documentation?", "Yes": { "Text": "Yes", "Do": "jump Yes" }, "No": { "Text": "No", "Do": "jump No" } } } ], "Yes": [ "h That's awesome!", "h Then you are ready to go ahead and create an amazing Game!", "h I can't wait to see what story you'll tell!", "end" ], "No": [ "h You can do it now.", "display message Help", "h Go ahead and create an amazing Game!", "h I can't wait to see what story you'll tell!", "end" ] }; ``` Script declaration on v2.0.0 ```javascript monogatari.script ({ // The game starts here. 'Start': [ 'show notification Welcome', { 'Input': { 'Text': 'What is your name?', 'Validation': function (input) { return input.trim ().length > 0; }, 'Save': function (input) { this.storage ({ player: { name: input } }); return true; }, 'Revert': function () { this.storage ({ player: { name: '' } }); }, 'Warning': 'You must enter a name!' } }, 'y Hi {{player.name}} Welcome to Monogatari!', { 'Choice': { 'Dialog': 'y Have you already read some documentation?', 'Yes': { 'Text': 'Yes', 'Do': 'jump Yes' }, 'No': { 'Text': 'No', 'Do': 'jump No' } } } ], 'Yes': [ 'y Thats awesome!', 'y Then you are ready to go ahead and create an amazing Game!', 'y I can’t wait to see what story you’ll tell!', 'end' ], 'No': [ 'y You can do it now.', 'show message Help', 'y Go ahead and create an amazing Game!', 'y I can’t wait to see what story you’ll tell!', 'end' ] }); ``` ### Independent Labels Declaring independent labels for your script is possible as always, and really useful to split your game into multiple files, here's a comparison on how this was achieved on the past and how it's done now. Individual Labels on v1.4.1 Singe Language ```javascript script["myLabel"]["English"] = [ "some statement", "other statement" ]; ``` Multi Language ```javascript script["myLabel"] = [ "some statement", "other statement" ]; ``` Individual Labels on v2.0.0 Single Language ```javascript monogatari.label ('myLabel', [ "some statement", "other statement" ]); ``` Multi Language ```javascript monogatari.label ('myLabel', 'English', [ "some statement", "other statement" ]); ``` ## 5. Script Actions / Statements The syntax for some of the actions you can perform on your script has been changed. Here's a small list of the ones that changed, however, it is best if you check their individual page to see all the new features! | Action | Old Syntax | New Syntax | | :--- | :--- | :--- | | [Show a character sprite](/v2/script-actions/characters) | `show <character_id> <sprite_id>` | `show character <character_id> <sprite_id>` | | [Hide a character sprite](/v2/script-actions/hide-character) | `hide <character_id>` | `hide character <character_id>` | | [Show an image](/v2/script-actions/show-image) | `show <image_id>` | `show image <image_id>` | | [Hide an image](/v2/script-actions/hide-image) | `hide <image_id>` | `hide image <image_id>` | | [Show a message](/v2/script-actions/message) | `display message <message_id>` | `show message <message_id>` | | [Show a scene / background image](/v2/script-actions/show-scene) | `scene <scene_id>` | `show scene <scene_id>` | | [Show a notification](/v2/script-actions/notifications) | `notify <notification_id>` | `show notification <notification_id>` | | [Show a particle system](/v2/script-actions/particles) | `particles <particles_id>` | `show particles <particles_id>` | | [Hide a particle system](/v2/script-actions/hide-particles) | `stop particles` | `hide particles` | ## 6. String Translations Previously, a file called strings.js was distributed with Monogatari where you would put all your string translations, mainly used for the UI. Now, those translations are handled internally but you can still add strings to them or modify them. Here's some comparison on how it worked before and how it works now. Strings declaration on v1.4.1 ```javascript const strings = { "Español": { "AdvanceHelp": "Para avanzar en el juego, presiona espacio o haz click.", "Audio": "Audio" } }; ``` Strings addition on v1.4.1 ```javascript strings["Español"]["AllowPlaybac"] = "Click here to allow audio playback"; ``` Strings declaration and addition on v2.0.0 ```javascript monogatari.translation ('Español', { 'AdvanceHelp': 'Para avanzar en el juego, presiona espacio o haz click', 'AllowPlayback': 'Click here to allow audio playback' }); ``` --- # Step 4: Make Your First Visual Novel > Write, save and test your own dialog, character and scene with live reload. Source: https://monogatari.io/v2/getting-started/step-4-make-your-first-visual-novel Section: Documentation Time to make it yours. Keep the dev server from [Step 2](/v2/getting-started/getting-monogatari) running (`bun run serve`) with your game open at [http://localhost:5100](http://localhost:5100) — thanks to live reload, you'll see every change the instant you save. ## 1. Play the sample first Play through the sample game once. It asks your name, greets you, and offers a Yes/No choice — a tiny tour of dialog, input and branching. Now let's see how it's built and change it. ## 2. Open your story Open `js/script.js` in your editor. Near the bottom you'll find the `monogatari.script({ … })` block — this is your whole story. Each label (like `'Start'`) holds a list of things that happen in order: ```javascript monogatari.script ({ // The game starts here. 'Start': [ 'show scene #f7f6f6 with fadeIn', 'y Hi! Welcome to Monogatari!', 'end' ] }); ``` Each item is one step. A plain line of text is narration; prefix it with a character's id (here, `y`) and that character says it. `show scene` sets the background — `#f7f6f6` is just a colour, but it can be an image too (you'll add one below). > [!NOTE] > The `'Start'` label is where every game begins. You can change the starting label > with the `Label` setting in [`options.js`](/v2/configuration-options/game-configuration). ## 3. Change a line — and watch it update Change the greeting: ```javascript 'y Hi! This is my very own visual novel!', ``` Save the file. Your browser reloads on its own — start the game again and your new line is there. That save-and-see loop is how you'll build your whole game. ## 4. Add more dialog Lines are just a list, so add as many as you like: ```javascript 'Start': [ 'show scene #f7f6f6 with fadeIn', 'y Hi! This is my very own visual novel!', 'y Adding dialog is as easy as adding lines to this list.', 'y Let me introduce a friend…', 'end' ], ``` ## 5. Add a character Find the `monogatari.characters({ … })` block above the script — the sample defines one character, `y` (Yui). Add your own beside it: ```javascript monogatari.characters ({ 'y': { name: 'Yui', color: '#5bcaff' }, 'm': { name: 'Mio', color: '#ff8fab' } }); ``` Now `m` can speak. Add a line to your script: ```javascript 'm Nice to meet you!', ``` There's much more you can give a character — sprites, expressions and more — in [Characters](/v2/building-blocks/characters). ## 6. Challenge: add a real scene Backgrounds are images you declare once and then `show`: 1. Drop an image into `assets/scenes/` — say `bedroom.jpg`. 2. Declare it in the `scenes` asset list in `js/script.js`: ```javascript monogatari.assets ('scenes', { 'bedroom': 'bedroom.jpg' }); ``` 3. Show it in your script: ```javascript 'Start': [ 'show scene bedroom with fadeIn', 'y Welcome to my room!', 'end' ], ``` Save, and there's your scene. More options in [Show Scene](/v2/script-actions/show-scene). ## The workflow you just learned ```mermaid flowchart LR edit["Edit a file<br/>(e.g. js/script.js)"] --> save["Save"] save --> reload["Browser reloads<br/>automatically"] reload --> play["Play your change"] play --> edit ``` Edit → Save → it reloads → play → repeat. That loop is the whole job. ## What's next You've made your first game! From here: - Tell your story: [Script & Labels](/v2/building-blocks/script-and-labels), [Dialogs](/v2/script-actions/dialogs), [Choices](/v2/script-actions/choices) - Bring it to life: [Characters](/v2/script-actions/characters), [Show Scene](/v2/script-actions/show-scene), [Play Music](/v2/script-actions/play-music) - Make it yours: [Player Preferences](/v2/configuration-options/player-preferences), [Style & Design](/v2/style-and-design) - Ship it: [Releasing Your Game](/v2/releasing-your-game) > [!TIP] > Something not working? Open your browser's developer console (`F12`) — Monogatari > prints helpful messages there when a line in your script isn't quite right. --- # Step 3: Get Familiarized > A quick tour of the project — what every folder and file is for. Source: https://monogatari.io/v2/getting-started/step-3-get-familiarized Section: Documentation Before you start writing, here's a quick tour so you know where everything lives. The good news: you'll spend almost all your time in just the `js/` folder. ## Folders | Folder | What's in it | | :--- | :--- | | `assets` | Everything your game shows or plays — images, audio, fonts, icons. Sub-folders like `characters/`, `scenes/`, `music/`, `sounds/` and `voices/` keep it organized. | | `js` | Where you make your game — your story, settings and variables. | | `style` | The CSS that controls how your game looks. See [Style & Design](/v2/style-and-design). | | `engine` | The Monogatari engine itself. You don't edit this — to update Monogatari, you replace this one folder. | ## The `js` folder — where you work This is the heart of your project. | File | What it's for | | :--- | :--- | | `script.js` | Your story. Characters, scenes, dialog and choices all live here. | | `options.js` | Game and engine settings — title, save slots, languages and more. See [Game Configuration](/v2/configuration-options/game-configuration). | | `storage.js` | Your custom variables — the things you want saved in the player's game (their name, affection points, flags…). See [Variables & Data Storage](/v2/building-blocks/data-storage). | | `main.js` | A place for any extra JavaScript you want to add. | ## Root files | File | What it's for | | :--- | :--- | | `index.html` | The page that hosts your game. | | `service-worker.js` | Powers offline play and [asset preloading](/v2/configuration-options/game-configuration/asset-preloading). | | `manifest.json` | Web-app metadata (name, icons) so your game can be installed to a device. | | `package.json` | Project info and the build scripts — `serve`, `build:web` and the desktop builds used when [releasing your game](/v2/releasing-your-game). | | `serve.ts` | The live-reload dev server you ran in Step 2. | > [!TIP] > When you update to a newer version of Monogatari, you only replace the `engine` > folder — your `js`, `style` and `assets` stay exactly as they are. ## Next steps Now you know your way around. Time to write — continue to [Step 4: Make your first visual novel](/v2/getting-started/step-4-make-your-first-visual-novel). --- # Step 2: Get Monogatari Running > Get the project template and start the live-reload dev server. Source: https://monogatari.io/v2/getting-started/getting-monogatari Section: Documentation With your [environment ready](/v2/getting-started/step-1-setup-your-environment), let's get a real Monogatari game running on your machine. ## 1. Get the template Get the latest Monogatari project template — a complete, ready-to-run project with the engine included and a small sample game already in place: - The quickest way is to download it from the official website, [monogatari.io](https://monogatari.io/). - Prefer git? Clone the [GitHub repository](https://github.com/Monogatari/Monogatari) and start from its `dist/` folder, which is the same template. Unzip it somewhere convenient and open the folder in your code editor. ## 2. Start the dev server Open a terminal in the project folder and run: ```bash bun run serve ``` You'll see: ```text Dev server running at http://localhost:5100 ``` Open [http://localhost:5100](http://localhost:5100) in your browser, and the sample game starts. That's it — Monogatari is running. > [!TIP] > The dev server has live reload built in. Leave it running: every time you save a > file, the browser refreshes automatically, so you see your changes instantly. You'll > rarely reload by hand again. To stop the server, press `Ctrl + C` in the terminal. > [!NOTE] > Don't want to use Bun? You can also just open `index.html` directly in your browser. > The game runs, but you lose live reload, and browser security around the `file://` > protocol disables service workers (asset preloading and offline support). The dev > server is the smoother path. ## What you got After unzipping, your project looks like this: ```text my-game/ ├── assets/ # Your images, audio, fonts and icons │ ├── characters/ │ ├── scenes/ │ ├── music/ │ └── … ├── engine/ # The Monogatari engine — you don't edit this ├── js/ │ ├── script.js # Your story: dialog, characters, scenes │ ├── options.js # Game & engine settings │ ├── storage.js # Your custom save variables │ └── main.js # Any extra JavaScript you want to add ├── style/ │ └── main.css # Your custom styling ├── index.html # The page that hosts your game ├── service-worker.js # Powers offline play & asset caching ├── serve.ts # The dev server you just ran └── package.json # Project info & build scripts ``` The next step tours these so you know exactly where to write your game. ## Next steps - [Step 3: Get familiarized](/v2/getting-started/step-3-get-familiarized) — Know where everything lives. - [Step 4: Make your first visual novel](/v2/getting-started/step-4-make-your-first-visual-novel) — Start writing. --- # Step 1: Set Up Your Environment > Install the three tools you need — a browser, a code editor, and Bun. Source: https://monogatari.io/v2/getting-started/step-1-setup-your-environment Section: Documentation A Monogatari game is a web project, so you'll use the same tools web developers use. There are just three, and you only set them up once. ## 1. A modern browser You already have one. For development we recommend [Chrome](https://www.google.com/chrome/) or [Firefox](https://www.mozilla.org/firefox/) — their developer tools (press `F12`) let you inspect your game and read error messages while you work. Your finished game will run in any modern browser. ## 2. A code editor Any text editor works (even Notepad), but a real code editor makes everything easier with syntax highlighting, auto-completion and multi-file editing. If you don't have a favourite yet, [Visual Studio Code](https://code.visualstudio.com/) is free, popular and beginner-friendly. ## 3. Bun Monogatari's project template uses [Bun](https://bun.sh/) — a fast JavaScript runtime — to run a local dev server with live reload and to build your game for release. Install it with a single command: macOS / Linux ```bash curl -fsSL https://bun.sh/install | bash ``` Windows (PowerShell) ```powershell powershell -c "irm bun.sh/install.ps1 | iex" ``` Then check it's installed: ```bash bun --version ``` If that prints a version number, you're ready. > [!TIP] > You can skip Bun and just open `index.html` directly in your browser — the game > still runs. But the dev server gives you live reload (the page refreshes itself > every time you save) and is needed to test features like asset preloading and > offline support, so the one-time install is well worth it. ## You're ready With a browser, an editor and Bun in place, continue to [Step 2: Get Monogatari running](/v2/getting-started/getting-monogatari). --- # Getting Started > Install Monogatari, run it locally with live reload, and write your first scene. Source: https://monogatari.io/v2/getting-started Section: Documentation Welcome to Monogatari! In this guide you'll go from nothing to a playable visual novel running in your browser, with a live-reload workflow that updates the moment you save a file. It takes about 15–20 minutes, and you don't need to be a programmer — if you can edit a text file, you can make a visual novel. ## What you'll build By the end you'll have the starter project running locally and you'll have written and tested your own dialog, a character, and a scene — the core loop of making a Monogatari game. ## The four steps 1. [Set up your environment](/v2/getting-started/step-1-setup-your-environment) — A browser, a code editor, and Bun. 2. [Get Monogatari running](/v2/getting-started/getting-monogatari) — Get the template and start the dev server. 3. [Get familiarized](/v2/getting-started/step-3-get-familiarized) — A quick tour so you know where everything lives. 4. [Make your first visual novel](/v2/getting-started/step-4-make-your-first-visual-novel) — Write, save, and watch it update live. > [!TIP] > Already comfortable with the web? The short version: get the template, run > `bun run serve`, open `http://localhost:5100`, and edit `js/script.js`. The rest of > this guide explains each part. ## Need help? - Check the [F.A.Q.](/v2/f-a-q) for common questions. - Ask the community on the [Forums](https://community.monogatari.io/). - Browse the rest of this documentation for detailed guides on every feature. --- # Welcome > Monogatari is a free, open-source web visual-novel engine. Start here to build your first game. Source: https://monogatari.io/v2/welcome Section: Documentation Monogatari is a free and open-source visual-novel engine that runs on the web. Your game is a real website, which means it runs almost anywhere — browsers, desktop and mobile — and you can extend it with anything the web can do. This documentation will take you from an empty folder to a released game. ## Start here New to Monogatari? Follow these in order: 1. [Getting Started](/v2/getting-started) — Install Monogatari and build your first scene. 2. [Building Blocks](/v2/building-blocks) — The core concepts: script & labels, characters, variables, actions and components. 3. [Script Actions](/v2/script-actions) — The full vocabulary for writing your story: dialog, choices, images, audio and more. 4. [Components](/v2/components) — The interface pieces you can restyle and reconfigure. 5. [Configuration Options](/v2/configuration-options) — Tune saving, languages, preloading and more. 6. [Style & Design](/v2/style-and-design) — Make the game look like yours. 7. [Releasing Your Game](/v2/releasing-your-game) — Ship to the web, desktop and mobile. ## How a Monogatari game fits together ```mermaid flowchart LR script["Your script<br/>(labels & statements)"] --> engine["Monogatari engine"] engine -->|matches each statement to an| action["Action"] action -->|updates| components["Components & screens"] components --> player(["What the player sees"]) player -.->|clicks / chooses| engine ``` You write a [script](/v2/building-blocks/script-and-labels) of statements; the engine matches each statement to an [action](/v2/building-blocks/actions); actions update the [components](/v2/components) that make up what the player sees. That loop — read a statement, run an action, update the screen, wait for the player — is the heart of the engine. ## Your game is a website While this documentation covers many parts of Monogatari, it doesn't cover everything you could do — because your VN is a website now, and the possibilities are endless. Anything you've seen on a website can be done in your game. So how do you find help for those things? Another benefit of your game being a website: there are lots and lots of tutorials out there. If you want something to happen when a player clicks an image, you can search "JavaScript click image" — there's no need to look for a Monogatari-specific answer. Everything that applies to a website applies to Monogatari too, even step-by-step web-development tutorials. ## Where to ask questions Of course, you are not alone! If you have a question, a problem, or just want some help, please reach out: - [Community Forums](https://community.monogatari.io/) — a friendly community of people making games just like you. - [Discord Server](https://discord.gg/sj4uPrP) — for something a little more immediate. - [Mastodon](https://mastodon.social/@HyuchiaDiego) or email (on my [website](https://hyuchia.com/)) — for other kinds of questions. - [GitHub](https://github.com/Monogatari/Monogatari) — to report bugs or request features. You can also check the [F.A.Q.](/v2/f-a-q) to see if your question has already been answered. ## Sponsor the project If you like Monogatari and would like to support it, becoming a sponsor is the best way to do it. There are many [ways to donate or sponsor the project](https://monogatari.io/#sponsor) — sponsors can also get benefits depending on their tier, like hosting for their games. --- # Translations > Translate Monogatari to other languages! Source: https://monogatari.io/v1/contribute/translations Section: Documentation v1 ## Overview Apart from translating the game contents, Monogatari's UI can also be translated to multiple languages. If you are someone who knows a language different from English, your help on translating the project is more than welcome! ## Getting started The file containing all the translations is found at `js/strings.js`. In it, you'll find multiple JSON objects describing the translations for each string on its own language. ```javascript "English": { "AdvanceHelp": "To advance through the game, press the space key or click.", "Audio": "Audio", "AutoPlay": "Auto", "AutoPlaySpeed": "Autoplay Speed", "Back": "Back", "BackButton": "Back.", "Cancel": "Cancel", "Close": "Close", "Confirm": "Do you want to quit?", "FullScreen": "Full Screen", "Help": "Help", "Hide": "Hide", "HideButton": "Hide Text.", "iOSAudioWarning": "Audio settings are not supported on iOS.", "Language": "Language", "Load": "Load", "LoadAutoSaveSlots": "Auto Saved Games", "LoadButton": "Open the Load Screen.", "Loading": "Loading", "LoadingMessage": "Wait while the assets are loaded.", "LoadSlots": "Saved Games", "LocalStorageWarning": "Local Storage is not available in this browser.", "Music": "Music Volume", "NoSavedGames": "No saved games.", "NoAutoSavedGames": "No automatically saved games.", "Overwrite": "Overwrite", "QuickButtons": "Quick Menu Buttons", "Quit": "Quit", "QuitButton": "Quit Game.", "Resolution": "Resolution", "Save": "Save", "SaveButon": "Open the Save Screen.", "SaveInSlot": "Save in slot", "Settings": "Settings", "SettingsButton": "Open the Settings Screen.", "Show": "Show", "SlotDeletion": "Are you sure you want to delete this slot?", "SlotOverwrite": "Are you sure you want to overwrite this slot?", "Sound": "Sound Volume", "Start": "Start", "Stop": "Stop", "TextSpeed": "Text Speed", "Voice": "Voice Volume", "Windowed": "Windowed" }, ``` To add a new language, simply copy one of these blocks and add your own translations! --- # Contribute > Contribute — Monogatari documentation. Source: https://monogatari.io/v1/contribute Section: Documentation v1 Browse the Contribute guides: - [Translations](/v1/contribute/translations) --- # Wait Source: https://monogatari.io/v1/script/wait Section: Documentation v1 What if you would want to wait some seconds before something happening? let's take a look at this script: ```javascript let script = { // The game starts here. "Start": [ "Hello there! I want you to wait 5 seconds now", "wait 5000", "Wow, that was a long time!", "end" ] }; ``` The `wait` statement allows us to make the game wait for a certain amount of time before continuing. In this case, the first dialog will be shown, then, when the player continues, the `wait` statement will make it wait for 5 seconds and then the next dialog will be shown. You may be wondering why it says `5000` instead of just `5` in order to wait 5 seconds, the reason behind it is that the `wait` statement accepts the time in milliseconds, therefore we have to make the conversion from seconds to milliseconds for it to work as we want. --- # Video Source: https://monogatari.io/v1/script/video Section: Documentation v1 Sometimes images and sound is just not enough and a video is needed. As always, you need to declare it first. To view the supported formats, you can take a look at [this page](http://www.w3schools.com/html/html5_video.asp). ```javascript var videos = { "Dandelion": "DandelionTimelapse.mp4" } ``` Then just use the command "Play" to play it!. ```javascript "play video Dandelion" ``` --- # Vibration Source: https://monogatari.io/v1/script/vibration Section: Documentation v1 You can make the mobile phones that support this feature vibrate! to do so, you just need the vibrate command which syntax is: If you want it to vibrate once: "vibrate \[time\]" If you want it to vibrate in a pattern: "vibrate \[time\] \[time\] \[time\] ..." The following will make the device vibrate for 100 milliseconds. ```javascript "vibrate 100" ``` While this will make it vibrate in a pattern: ```javascript "vibrate 100 200 300 200 100" ``` --- # Text Source: https://monogatari.io/v1/script/text Section: Documentation v1 Show Text The say statement is used... well, for a character to say something. The syntax is as follows: `"[Character Identifier] [Text to Say]"` ```javascript "e Hi! My name is Evelyn." ``` It also accepts HTML, so you can show many things in a text like the Font Awesome icons. ```javascript "e The <span class='fa fa-arrow-left'></span> button is the back button, press it to return to a previous state of the game.", ``` If no character identifier is given, it will be considered as a narration and no name will be shown. ```javascript "This would be a narrator." ``` #### Clear the Text You may want in some point to clear/remove the text. There's a "clear command" for that. ```javascript "clear" ``` #### Side Images If you've defined the "Side" property for your characters, adding a list of images to show, you can use them as side images with each dialog, to do so, you should use a format like this one: ```javascript "e:Smiling Hi! My name is Evelyn." ``` This assumes you have a Side image called Smiling, which means with every dialog you can specify what side image to use. If you add the "Face" property then that image will be shown with every dialog without the need of specifying it inside the statement. --- # Storage Source: https://monogatari.io/v1/script/storage Section: Documentation v1 The storage is an object in which we can put everything we want to save when a player saves the game. We have to create a property where the player can store his data in it. So in `storage.js` we start with... ```javascript var storage = { player: { // add property name: "" // add placeholder } } // Syntax var storage = { // object property1: { // property of object placeholder1: 0, // integer of property placeholder2: "" // string of property } } ``` If we now want to get the name after saving one in there, this would look like this in the `script.js`. ```javascript storage.player.name = "Monogatari"; // example for saving a name "{{player.name}} is a visual novel engine." // example for display the name ``` To offer more possibilities in the game and to have a simpler overview in the storage file, you can create as many properties as you want, just make sure to use a comma before adding a property. Here is an example... ```javascript var storage = { player_info: { name: "", age: "", city: "" }, player_stats: { hp: 100, mp: 100, inventory: { gold: 1000, iron: 10 } } } ``` Which can be accessed as follows $examples$... ```javascript {"Input": { // call input statement "Text": "What is your name?", // show text of the input box "Validation": function(input) { return input.trim().length > 0; }, // validation rule for the value "Save": function(input) { // call save statement and start a function storage.player_info.name = input; // store the value in the variable name storage.player_info.age = 18; // store 18 in the variable age }, }}, function (){ storage.player_info.name = "Georg"; // save "Georg" in variable name (overwrite old value) storage.player_stats.hp -= 50; // decrease hp minus 50 storage.player_stats.inventory.gold += 250; // add 250 gold }, "{{player_info.name}} is {{player_info.age}} years old.", // call name = "Georg" and age = 18 "{{player_stats.mp}} costs the ability 'Fire Storm'.", // call mp = "100" "{{player_stats.inventory.gold}}g is in his bag of gold." // call gold = 1250 ``` If you want to see an example of the stat system $created with storage.js$, [click me](https://hyuchia.com/Monogatari-Stat-System/). --- # Split Files Source: https://monogatari.io/v1/script/split Section: Documentation v1 ### Splitting up your Monogatari Script Monogatari games are made pretty much by the script you create, that script is all wrapped up in one single variable and file. This may be convenient at first but as your game grows up, the script may start to be a bit too big for it to easily read, it can become somewhat stressful even and in worse cases, it may slow down your text editor while you make changes to it. In order to prevent this, you can split your script into several files. Spliting your script may also be a good idea when having many branches of your story, when you want to make proofreading somewhat simpler and of course really helpful when your game is available in multiple languages. This documentation page was Sponsored by [My Awesome Patrons](https://www.patreon.com/Hyuchia), thanks a lot guys! #### So, how to do it? Figured the best way to show you how to do it was to provide an example project so you can [download it here](https://datadyne.perfectdark.space/monogatari/community/samples/Monogatari-Split-Files.zip). Splitting your script is more about splitting labels really, remember that every label is like a chapter or a scene in your visual novel so splitting your game in labels makes a lot of sense, of course splitting those labels in different files makes even more sense. Each label has an id that you specify, the initial label $as in the one with which your games always starts$ is the one with the "Start" id. You then use the "jump" statements to go from there to any other label you created. To have a label in another file, you just need to declare it like this: ```javascript script["OtherLabel"] = [ "This is another label!" ]; ``` That declaration is the same as if you had the following $I'm omitting the contents of the Start label for simplicity$: ```javascript var script = { "Start": [...], "OtherLabel": [ "This is another label!" ] }; ``` That means you can declare labels not only in the var script = {...}; code but also from outside of it. `"OtherLabel"` is being used as the id but remember it can be pretty much anything you want. Since we are splitting things up, that means the script.js file will not longer be the only place where our story resides. You'll be saving that label $the first code showed in this post$ in other file, remember you need to load that file as well, so just add it in your index.html file, right below the line that says: ```markup <script src="js/script.js"></script> ``` Let's suppose you are saving that level on a file with the same name: OtherLabel.js, to load it. Just insert another script tag like this one: ```markup <script src="js/OtherLabel.js"></script> ``` If everything worked up correctly, you should be able to jump from one label to another even when they are in different files. Take a look at the sample project from the link above, it will definitely show you what it is all about and you'll probably get a better understanding of it all, it is really simple and can be quite advantageous. #### Wait but what happens if there are too many files now? Of course you may get to a point ehere there are simply too many files, if you are serving your game online, that can cause a slower load time which is of course not what we want. For now, the best solution is to copy and paste all the contents of the files you created into a single one. Yes, you can copy and paste them just as they are one after another, the order is not really important in most cases, the only one that truly matters is the script.js file which should always go first. This would also need to be done if you are obfuscating your code, it's a lot easier to obfuscate just one file than a lot of them. This solution is of course not ideal, you can find many utilities for concatenating files, some are stand alone programs, some are websites and some are development utilities. I personally would recommend those development utilities such as [this one](https://www.npmjs.com/package/gulp-concat/) but the problem is that they are not the easier to use and requires you to install other things therefore you may want to stick with the manual solution or find a nice utility that does it. This is one of the features I'm planning to add to the Monogatari Studio but haven't really got the time to work on it. Nonetheless, I hope you find the file splitting somewhat useful, once you find a nice work flow around it, you'll see how simple it can get! --- # Scenes Source: https://monogatari.io/v1/script/scenes Section: Documentation v1 The scenes clear the screen and change the background. They will also remove the text, characters and images displayed. You can either use images or CSS properties like colors as backgrounds. If you'll use images, must declare them first, every scene image file must be placed in the scenes directory inside the img directory. Remember to add these files to your `service-worker.js` file if you want to improve asset preloading as stated in the [Asset Preload Section](/v1/configuration/asset-preloading) ```javascript var scenes = { "mountain": "mountain.svg", "sea": "sea.png" } ``` Now, to change the scene, just use the scene command. Syntax: "scene \[Scene Identifier\]" ```javascript "scene mountain" ``` If you'll use css to set your own background style, you must use the scene command as well. Syntax: "scene \[CSS\]": These are valid ways to use it: ```javascript "scene #fff" "scene rgb(0,0,0)" "scene url('img/scenes/mountain.svg')" ``` #### Animations Since Monogatari v1.3.2, it is possible to use the same animations for characters and scenes, to use an animation to display your scene, you must use the scene command as follows: Syntax: "scene \[CSS or Image Identifier\] with \[Animation Name\]" ```javascript "scene mountain with fadeIn" ``` Remember you can see the list of animations and visualize them [here](https://daneden.github.io/animate.css/). You can also use CSS to create your own animations, you'll have to apply them to a CSS class and then use the scene statement as follows: Syntax: "scene \[CSS or Image Identifier\] with \[CSS Class Name\]" For example, note the following CSS code creating a simple Ken Burn Animation: ```css .ken-burn { animation-name: ken-burns; /* Name of the animation to use / animation-duration: 30s; animation-iteration-count: infinite; / 1 if it should only move once / animation-timing-function: ease; animation-fill-mode: forwards; animation-delay: 0s; -moz-transition: ease 1s all; -o-transition: ease 1s all; -webkit-transition: ease 1s all; transition: ease 1s all; } @keyframes ken-burns { 0% { -webkit-transform: translateX(0); } 50% { -webkit-transform: translateX(-500px); } 100% { -webkit-transform: translateX(0px); } } ``` In order to use that animation within your game, it would be as simple as this: ```javascript "scene mountain with ken-burn" ``` --- # Particles Source: https://monogatari.io/v1/script/particles Section: Documentation v1 You can show particles in your game, useful for representing rain, snow, fire, explosions etc! You must first declare your particles: ```javascript var particles = { "Snow": { "particles": { "number": { "value": 400, "density": { "enable": true, "value_area": 800 } }, "color": { "value": "#fff" }, "shape": { "type": "circle", "stroke": { "width": 0, "color": "#000000" }, "polygon": { "nb_sides": 5 }, "image": { "src": "img\/github.svg", "width": 100, "height": 100 } }, "opacity": { "value": 0.5, "random": true, "anim": { "enable": false, "speed": 1, "opacity_min": 0.1, "sync": false } }, "size": { "value": 10, "random": true, "anim": { "enable": false, "speed": 40, "size_min": 0.1, "sync": false } }, "line_linked": { "enable": false, "distance": 500, "color": "#ffffff", "opacity": 0.4, "width": 2 }, "move": { "enable": true, "speed": 6, "direction": "bottom", "random": false, "straight": false, "out_mode": "out", "bounce": false, "attract": { "enable": false, "rotateX": 600, "rotateY": 1200 } } }, "interactivity": { "detect_on": "canvas", "events": { "onhover": { "enable": true, "mode": "bubble" }, "onclick": { "enable": true, "mode": "repulse" }, "resize": true }, "modes": { "grab": { "distance": 400, "line_linked": { "opacity": 0.5 } }, "bubble": { "distance": 400, "size": 4, "duration": 0.3, "opacity": 1, "speed": 3 }, "repulse": { "distance": 200, "duration": 0.4 }, "push": { "particles_nb": 4 }, "remove": { "particles_nb": 2 } } }, "retina_detect": true } } ``` Then, whenever you want to show them, just use the particles command: ```javascript "particles Snow" ``` And to stop them: ```javascript "stop particles" ``` If you want more examples, you can find them in the [GitHub page of the library](https://github.com/VincentGarreau/particles.js/) --- # Notifications Source: https://monogatari.io/v1/script/notifications Section: Documentation v1 A notification may be useful to let the user notice something. You could also use it as an achievement system for your game. First you need to declare your notification, it consists on an Identifier, Title, a A subtitle and the message body. ```javascript var notifications = { "SampleNotification":{ title: "Hey!", body: "This is a notification", icon: "img/logo.png" }, } ``` Next, to show them up in your game, yo just need the notify command. ```javascript "notify SampleNotification" ``` If you want your notification to hide after a while, you can tell after how many miliseconds it should go away: ```javascript "notify SampleNotification 300" ``` That way, the notification will pop up and then go away after the 300 miliseconds have passed. --- # Messages Source: https://monogatari.io/v1/script/messages Section: Documentation v1 A message is a nice way of showing the user some content. You could also use it as a mailbox or something for your game. First you need to declare your message, it consists on an Identifier, Title, a A subtitle and the message body. ```javascript var messages={ "SampleWriting":{ "Title": "Some sample writing", "Subtitle": "From Evelyn", "Message":"Just look how easy it is!<br><img src='img/sample.png'>" }, } ``` As you can see, you can also write HTML on them! Next, to show them up in your game, yo just need the Display Message command. ```javascript "display message SampleWriting" ``` Each message has a close button so the user is able to close it when he's finished reading it. --- # Labels Source: https://monogatari.io/v1/script/labels Section: Documentation v1 ### Chapters Called Labels Labels are just like the book's chapters, they define parts in your game. Take a look at this sample script: ```javascript var script = { "Start":[ "This is a statement." ] } ``` See that "Start" string? That's how a label is defined. Your game will always start in that "Start" label and every game must have one. Inside it, you'll see a statement, which are the lines that tell your story and the way you'll do many things. As labels are as chapters, you can have as many as you want! ```javascript var script = { "Start":[ "This is a statement.", "jump mylabel" ], "mylabel":[ "This is another statement.", "Pretty easy huh?" ] } ``` See that `"jump mylabel"`? that's how you can change between labels, the jump statement will take you to the label you give it. --- # JavaScript Source: https://monogatari.io/v1/script/javascript Section: Documentation v1 Even though you can put more Javascript code in the main.js file and do a lot of things there, sometimes we want to do something in some part of our game. This is why you can also put some Javascript inside your game's script. To do it, you can actually using JavaScript functions. Yes, just like you would on any other JS file, you can use function syntax inside your script. To control the flow of your game, you can make the function return either true $Will immediately execute the next statement.$ or false $Will wait until the user clicks again.$ if it does not return one of those two, it will wait by default. Example: ```javascript "Hi there!", function(){ alert("This is pretty useful!"); return true; // Will make the engine execute the next statement when the function finishes. }, "Isn't it?" ``` While that may be ok for a few functions, as you can see after a while your code starts to become more complicated, a way to simplify things is declaring the functions before your script and then just using the name to call it in the script like this: ```javascript function sendAlert(){ alert("This is pretty useful!"); return true; } var script = { // The game starts here. "Start": [ "Hello, after this the function will be run.", sendAlert, // You can use just the name of the function! "Well, that looks a lot better!" ] } ``` Using that technique will make your game a lot more easy to debug and update! #### Async Functions While the advanced way adds a lot of more possibilities to your game, it still doesn't solve the fact that you may need to realize some async tasks such as a request or other activities. Since v1.3.2, using [JavaScript Promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) is possible. ```javascript function asyncFunction(){ return new Promise((resolve, reject) => { // All your code should be here setTimeout(function(){ // You need to resolve the promise once your task is done resolve("Success!"); }, 2150); }).then((successMessage) => { alert( successMessage); return true; }); } var script = { // The game starts here. "Start": [ "Hello, after this the function will be run.", asyncFunction, "Well, that looks a lot better!" ] } ``` Just as with the common functions, if you return a true value from your promise, the next statement will be executed as soon as it's done and will wait if you return anything else. The game will also block on the meantime so the player won't be able to continue until the Promise is resolved. #### Reversible Functions So far, we've been using normal JavaScript functions to achieve more functionality but one problem was that this functions were not reversible, meaning that the players were not able to go back over a function. Let's see what we mean by that, let's say you are building some kind of RPG elements in your game and thus your player has stats. Normally, those stats would be declared inside your storage variable like this: ```javascript "use strict"; // Persistent Storage Variable let storage = { player: { intelligence: 0, ability: 0, strength: 0 } }; ``` Now, inside your script you would probably make some modifications of those stats depending on what the user does or how the story goes. ```javascript let script = { // The game starts here. "Start": [ "h Currently you have {{player.intelligence}} points of Intelligence but you seem far more intelligent, how about we add five points?", function () { storage.player.intelligence += 5; return true; }, "h There you have it, you now have {{player.intelligence}} points of Intelligence", "end" ] } ``` So, if we played this game, the first text would appear, then after we click for the next one, the function would be run adding 5 points to our intelligence stat and immediatly would show the next text. If we wanted to go back to the first text it wouldn't be possible. This is mainly due to Monogatari not knowing what you are doing exactly in your function, if it were to allow you to go back, we could be getting infinite points just by going back and playing it again because there is no way to know what changed. To solve this problem and allow users to go back, Monoagatari v1.4 introduced reversible "Function" objects, as with all the special script objects, these are defined in a JSON format, let's take a look at how the same situation as above would look like: ```javascript let script = { // The game starts here. "Start": [ "h Currently you have {{player.intelligence}} points of Intelligence but you seem far more intelligent, how about we add five points?", {"Function":{ "Apply": function () { storage.player.intelligence += 5; return true; }, "Revert": function () { storage.player.intelligence -= 5; } }}, "h There you have it, you now have {{player.intelligence}} points of Intelligence", "end" ] } ``` As you can see, we replaced the function with a `"Function"` object which has 2 properties, an `"Apply"` function which will run when going over the game and the `"Revert"` function which will be run when going back. This now solves the previous problem we had since we are using `"Apply"` to add the 5 points and `"Revert"` to substract them in case the player went back and thus makes possible for players to go back even when a function was run. Just as with common functions, you can use Promises and also control the flow of the game by returning `true` or `false` in the `"Apply"` function. --- # Input Source: https://monogatari.io/v1/script/input Section: Documentation v1 ### Accepting user Input There are many cases where we need input from the user, like to ask their name. There is an input statement for this. This is a sample script with an input statement: ```javascript var script = { // The game starts here. "Start": [ "You'll see an input next", {"Input": { "Text": "What is your name?", "Validation": function(input) { return input.trim().length > 0; }, "Save": function(input) { storage.player.Name = input; }, "Warning": "You must enter a name!" } }, "Hi {{player.Name}} Welcome to Monogatari!" ] } ``` As you can see, the input statement is in fact an object, with 4 properties, Text, Validation, Save and Warning. #### Text The text to be displayed in the input dialog #### Validation The validation function, there are times when you want to validate the user input, to see if it's not empty for example, the Validation property should be a function returning a boolean, the validation process is up to what you want. #### Save The save function, what Monogatari will do with the input once it's validated, normally you would save it on storage, but you can do whatever you want with it, the save property is then a function that receives the input, what you do with it is also uo to you. #### Warning The warning property is just the message that will be shown in case the input fails the validation, something useful for the player to know what you expect from them. --- # Images Source: https://monogatari.io/v1/script/images Section: Documentation v1 The show statement is used to show a character or an Image. The syntax is as follows: In case of characters: "show \[Character Identifier\] \[Image Key\] \[position\] with \[Animation\]" In case of Images: "show \[Image Identifier or File\] \[position\] with \[Animation\]" Every position is a CSS class, so you can declare your own! The ones available by default are: center, left and right. Take a look at more css classes in the "Designing my Game" section, you can also declare your own. #### Showing Characters Remember every character image must be declared in the character. ```javascript "show e normal center with fadeIn", ``` The [animation](https://daneden.github.io/animate.css/) is completely optional, and if a position is not given, it will show in the center by default. ```javascript "show e normal", "show e normal with fadeIn", ``` To hide a character, you only need the "hide" command. Syntax: "hide \[Character Identifier\] with \[Animation\]" ```javascript "hide e" ``` You can also hide them with one of the [exit animations](https://daneden.github.io/animate.css/) available. ```javascript "hide e with fadeOut" ``` All Characters images must be inside the characters subdirectory of img. #### Showing Images In case of images, they can be declared to use an identifier or you can also use the file's name. The root directory for images will always be img. ```javascript "show flower center with fadeIn", // If flower is declared "show flower.png center with fadeIn" // If flower isn't declared ``` To hide this images, you'll use the hide command as well. ```javascript "hide flower", // If flower is declared "hide flower.png" // If flower isn't declared ``` You can use the same animations and positions when showing characters or images. --- # Conditionals Source: https://monogatari.io/v1/script/conditionals Section: Documentation v1 Chances are, at some point you'll want to control the flow of your game depending on certain conditions, like jumping to certain labels or even show different dialogs depending on some condition. To do this, Monogatari has Conditional objects, let's take a look at this Conditional taken from the Demo: ```javascript {"Conditional": { "Condition": function(){ return storage.evelyn_name == "Evelyn"; }, "True": "e Evelyn... That's a lovely name! I love it!", "False": "e {{evelyn_name}}... Yeah, sounds good!" }}, ``` As you can see, a Conditional is made up of 3 properties, a `"Condition"`, the function that will be used to determine whether the condition is met or not. In these case, we are checking if the variable `storage.evelyn_name` is equal to `"Evelyn"`, if the condition returns `true`, the statement inside the `"True"` property will be run, if it's false then the statement inside the `"False"` property will be run. In this case, those statements are dialogs so that simply means that if the condition is true, the first dialog will be shown, if not then the second one will be shown. Of course dialogs is not the only thing we can do here, we can also use Conditionals to jump to certain labels like this: ```javascript {"Conditional": { "Condition": function(){ return storage.played == true; }, "True": "jump Played", "False": "jump NewGame" }}, ``` --- # Choices Source: https://monogatari.io/v1/script/choices Section: Documentation v1 But what is a Visual Novel without choices right? Choices are built as JSONs, with the key 'Choice', and every choice available as a sub-item. Every choice requires 2 properties: the text to display and what to do when it's clicked. ```javascript {"Choice":{ "Developer":{ "Text": "I'm a developer.", "Do": "jump Developer" }, "Writer":{ "Text": "I'm a writer.", "Do": "jump Writer" }, "Artist":{ "Text": "I'm an artist.", "Do": "jump Artist" }, "Player":{ "Text": "I'm a Player.", "Do": "jump Player" } }} ``` ## Conditional Choices There are some cases where you would only want to show a choice if certain conditions are met. Conditional choices are possible by adding a simple 'Condition' function. For this example, let's assume this is your `storage` variable: ```javascript "use strict"; // Persistent Storage Variable let storage = { played: false }; ``` As you can see, we added a 'played' variable inside the storage and set its default to `false`. Now, let's see what would happen with the following Choices: ```javascript {"Choice":{ "Developer":{ "Text": "I'm a developer.", "Do": "Developer" }, "Player":{ "Text": "I'm a Player.", "Do": "Player", "Condition": function () { return storage.played == true; // The "Player" option will only be shown if this returns true. } } }} ``` `'Player'` will only be shown if the `'played'` variable we added is `true`, since we defined it as `false`, then it won't be shown however, if somewhere along the script we were to change that variable to `true` then this choice will be shown. ## Showing Text when Showing the Choices You might want to show a dialog along with the choices, this is possible adding a text property inside the object: ```javascript {"Choice":{ "Dialog": "e Before I continue, let me ask you, what are you?", "Developer":{ "Text": "I'm a developer.", "Do": "Developer" }, "Player":{ "Text": "I'm a Player.", "Do": "Player", "Condition": function () { return storage.played == true; // The "Player" option will only be shown if this returns true. } } }} ``` That way the `'Dialog'` property is the one that will be shown with the choices, as you can see, just like with normal dialogs, you can specify what character is the one talking and take full advantage of other things like side images on it. ## Styling your Buttons The `'Class'` property allows you to give a CSS class to your buttons for special styles. Suppose you had the following CSS in your `main.css` file: ```css .boldedText { font-weight: bold; } .italicText { font-style: italic; } ``` The `boldedText` and `italicText` classes can then be applied to your buttons by setting their `'Class'` properties in your script, like so: ```javascript {"Choice":{ "FirstOption":{ "Text": "Yes", "Do": "jump label1", "Class": "boldedText" //A css class to apply to the button. }, "SecondOption":{ "Text": "No", "Do": "jump label2", "Class": "italicText" } }}, ``` This way, the `'Yes'` button will have its text bolded and the `'No'` button will have its text _italicized_. You can also use CSS styling to do things like give buttons background images and make the text on them invisible, so you can have buttons with pictures! --- # Characters Source: https://monogatari.io/v1/script/characters Section: Documentation v1 Declaring characters is really simple! First, you need an identifier, this is what you'll use for the "Say" and "Show" commands. We'll choose the identifier "e" for this tutorial. ```javascript var characters = { "e":{ } } ``` Each character has many properties, like the name that is shown to the player, and the color for it. ```javascript var characters = { "e": { "Name": "Evelyn", // The name that will be shown when this character speaks. "Color": "#00bfff" // It could also be an rgb or rgba value. } } ``` Since we are building visual novels, we also need images for our characters! You need the Directory inside the img directory where your files will be placed, and assign a simple identifier to each file. ```javascript var characters = { "e": { "Name": "Evelyn", "Color": "#00bfff", "Directory": "Evelyn", // Optional "Images":{ // Images Identifier for the "Show" statement. "Normal": "normal.png", "Mad": "hmph!.png", "Doubt": "uhh.png", "Disappointed":"ngggg....png", "Happy": "hehehehe.png" }, "Face": "face.png", // Optional, side image to show every time the character speaks. "Side": { // Side images identifiers to show on dialogs when the character speaks with a colon and side image name, like e:Smiling "Smiling": "smiling.png" } } } ``` * The directory attribute is a subdirectory of characters where the images will be pulled, if no Directory is given, it will be assumed to be the characters directory itself. --- # Audio Source: https://monogatari.io/v1/script/audio Section: Documentation v1 Everyone enjoys music while playing, and special effects and of course, voices. The "Play" command is the way of doing it. You can declare them so they'll have an identifier, if you prefer using the file's name that's ok, just remember that either case they must be in the corresponding directory $music, voice or sound$ inside the audio directory. To view the supported formats, you can take a look at [this page](http://www.w3schools.com/html/html5_audio.asp). Declarations: ```javascript var music = { "Theme": "song.mp3" } var voice = { "F1": "f1.mp3" } var sound = { "Rain": "rain.mp3" } ``` #### Music Playing music: With declaration: ```javascript "play music Theme loop" // If loop isn't there, it will only play once. ``` Without declaration: ```javascript "play music song.mp3 loop" ``` You can stop or pause music: ```javascript "stop music" ``` ```javascript "pause music" ``` #### Voice ```javascript "play voice f1" ``` #### Sound With declaration: ```javascript "play sound Rain loop" // If loop isn't there, it will only play once. ``` --- # Script > Script — Monogatari documentation. Source: https://monogatari.io/v1/script Section: Documentation v1 Browse the Script guides: - [Audio](/v1/script/audio) - [Characters](/v1/script/characters) - [Choices](/v1/script/choices) - [Conditionals](/v1/script/conditionals) - [Images](/v1/script/images) - [Input](/v1/script/input) - [JavaScript](/v1/script/javascript) - [Labels](/v1/script/labels) - [Messages](/v1/script/messages) - [Notifications](/v1/script/notifications) - [Particles](/v1/script/particles) - [Scenes](/v1/script/scenes) - [Split Files](/v1/script/split) - [Storage](/v1/script/storage) - [Text](/v1/script/text) - [Vibration](/v1/script/vibration) - [Video](/v1/script/video) - [Wait](/v1/script/wait) --- # Web Source: https://monogatari.io/v1/release/web Section: Documentation v1 Monogatari was built with this in mind, releasing your game online and thus making it available to play almost anywhere! To release your game online, you should first take care of the following steps. ## Complete your Meta Tags Inside your `index.html` file, you'll notice there's a lot of meta tags, every single one of them have the purpose of improving your game SEO so it comes up in search result, make social sharing better and improve the experience on mobile devices. Filling them up is not necessary for your game to work but when releasing it online, failing to do so may result in a poor experience for your players. Many come already pre-filled but others are for you to fill in, in the case of all the icon files, since v1.3.2 Monogatari provides placeholder icons inside the `img/icons/` directory, be sure to replace those with your own as well as the `favicon.ico` file before releasing your game. Here is the section of meta tags you'll find and that need to be filled in case they aren't already: ```markup <title></title>  <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1"> <meta name="description" content="">  <meta name="keywords" content=""> <meta name="author" content="">   <meta property="og:image" content="http://" />  <meta property="og:description" content="" />  <meta property="og:site_name" content="" />  <meta property="og:url" content="http://" />  <meta property="og:title" content="" />   <meta itemprop="name" content="">  <meta itemprop="description" content="">  <meta itemprop="image" content="http://">   <meta name="twitter:card" content="summary_large_image">  <meta name="twitter:domain" content="">  <meta name="twitter:site" content="@">  <meta name="twitter:title" content="">  <meta name="twitter:description" content="">  <meta name="twitter:creator" content="@">  <meta name="twitter:image:src" content="http://">   <meta name="mobile-web-app-capable" content="yes"> <link rel="icon" sizes="192x192" href="img/icons/icon_192x192.png">  <link rel="icon" sizes="128x128" href="img/icons/icon_128x128.png">   <meta name="apple-mobile-web-app-title" content="">  <meta name="apple-mobile-web-app-capable" content="yes"> <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">  <link rel="apple-touch-icon" href="img/icons/icon_60x60.png">  <link rel="apple-touch-icon" sizes="76x76" href="img/icons/icon_76x76.png">  <link rel="apple-touch-icon" sizes="120x120" href="img/icons/icon_120x120.png">  <link rel="apple-touch-icon" sizes="152x152" href="img/icons/icon_152x152.png">  <link rel="apple-touch-icon" sizes="152x152" href="img/icons/icon_167x167.png">  <link rel="apple-touch-icon" sizes="152x152" href="img/icons/icon_180x180.png">   <meta name="msapplication-TileColor" content="">  <meta name="application-name" content="" />  <meta name="msapplication-tooltip" content="" />  <meta name="msapplication-starturl" content="http://" />  <meta name="msapplication-square70x70logo" content="img/icons/icon_70x70.png" />  <meta name="msapplication-square150x150logo" content="img/icons/icon_150x150.png" />  <meta name="msapplication-wide310x150logo" content="img/icons/icon_310x150.png" />  <meta name="msapplication-square310x310logo" content="img/icons/icon_310x310.png" />  <link rel="publisher" href="">  <meta name="theme-color" content=""> <link rel="shortcut icon" href="img/favicon.ico" />  <link rel="canonical" href="">  ``` ## Optimize your images Optimizing your images is imperative to provide a better experience, we all hate when pages take a lot of time to load, even when using the preload features built in on Monogatari, optimizing your images will provide a better experience, the method you choose to do so is entirely yours to pick. ## Improve Asset Loading To improve asset loading and enable offline playing, you'll have to complete the files list you need to save in the cache for your game to be able to work, information about this can be found in the [Asset Preload Configuration](/v1/configuration/asset-preloading). ## Improve the Mobile experience A manifest.json file is shipped on Monogatari since v1.3.2, this file is needed to provide a better mobile experience, specifically it's another requirement to transform your app in a [Progressive Web App](https://en.wikipedia.org/wiki/Progressive_web_app) which will enable a great experience for your users, specially if they [add your game to their home screen](https://www.howtogeek.com/196087/how-to-add-websites-to-the-home-screen-on-any-smartphone-or-tablet/) which you should encourage! adding it to homescreen will show your game icon just as with other app, then show a splash screen when loaded using the `background_color` and icons defined in your `mainfest.json` file and if you've [set up correctly your service worker cache](/v1/configuration/asset-preloading), it will also be possible to play it offline, making it work almost like a native mobile app, an experience your players will truly love. Inside this file you'll only need to pay attention to four properties: ```javascript "short_name": "Monogatari", // Maximum 12 characters "name": "Monogatari Visual Novel", // Maximum 45 characters "background_color": "#F7F7F7", // Background color for the Splash Screen "theme_color": "#F7F7F7", // General theme color for the browser ``` For more information about the manifest and what every property does, [check this site](https://developer.mozilla.org/en-US/docs/Web/Manifest). ## Upload your game --- # Mobile Source: https://monogatari.io/v1/release/mobile Section: Documentation v1 Creating a "Native" web app is another way to distribute your game, there are many ways to do it. Option 1: Building a Native app with a WebView pointing to your game files. Option 2: Using something like Apache Cordova. Again, I will not cover this right now, but this is the web we are talking about, you'll find plenty of tutorials out there, remember your VN is a WebPage now! --- # Desktop App Source: https://monogatari.io/v1/release/desktop Section: Documentation v1 Sure, you could just send a zip to everyone and people would only have to open the index.html to play your game, but if you want to distribute your game as a desktop app, you'll be able to use [Electron](http://electron.atom.io/) for it since Monogatari already has the basics for it. First, finish your game of, you'll use the same files for the desktop version so if it's ready for the web, then you're ready! If you prefer it, you can follow the [Official Electron's Documentation](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md) instructions for this. Next, download the latest Electron binaries from it's [GitHub Page](https://github.com/atom/electron/releases) you'll need to download all the binaries for every system you'd like to build your game for as well as the arquitectures. At the moment this was written the latest version is electron v0.29.1, so assuming we want to build our game for every OS, then I'll download this files: 1. electron-v0.29.1-darwin-x64.zip $Mac OS X$ 2. electron-v0.29.1-linux-arm.zip $Linux ARM Arquitecture$ 3. electron-v0.29.1-linux-ia32.zip $Linux 32 Bit Arquitecture$ 4. electron-v0.29.1-linux-x64.zip $Linux 64 Bit Arquitecture$ 5. electron-v0.29.1-win32-ia32.zip $Windows 32 Bit Arquitecture$ 6. electron-v0.29.1-win32-x64.zip $Windows 64 Bit Arquitecture$ And yes, that's a lot of files, but everyone of those files is your future game!, when you download them uncompress them and you'll realize they're already built apps, you can open it, but now we have to put or game on it. In order to do so, follow this instructions #### For OS X Right Click the Electron.app and select "Show Package Contents" $If you're not on OS X you'll see the Electron.app as a simple directory so just open it$ Now create a directory named "app" in Electron.app/Contents/Resources/ and copy your VN files to it. Open the package.json file that comes with Monogatari and write your VN's name and version, once you've done that, just save the file and close it. With this done you'r game will now run as an app however we still need to custimize it. You should change the icon $icns$ file for your game's icon. Next, you need to rename the CFBundleDisplayName, CFBundleIdentifier and CFBundleName fields in following files: Electron.app/Contents/Info.plist Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist And finally Change the name of the Electron.app to to any name you like. That's it, now you can distribute your application for Mac OS X #### For Windows Create a directory named "app" in resources/ and copy your VN files to it. Open the package.json file that comes with Monogatari and write your VN's name and version, once you've done that, just save the file and close it. Finally rename the electron.exe to any name you like. That's it, now you can distribute your application for Windows, the same procedure applies to all the arquitectures. Sadly you can't change the icon as easy as in Mac, however you can search for a tool to do it or if you dare, you could Rebuilding Electron from source to achive this. #### For Linux Create a directory named "app" in resources/ and copy your VN files to it. Open the package.json file that comes with Monogatari and write your VN's name and version, once you've done that, just save the file and close it. Finally rename the electron executable to any name you like. That's it, now you can distribute your application for Linux, the same procedure applies to all the arquitectures. #### Wrapping up... Please check the [Official Electron's Documentation](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md) as well, I'm sure you'll find --- # Chrome App Source: https://monogatari.io/v1/release/chrome Section: Documentation v1 If you want people to play your game offline, then they must have all the files, and even though you could give them a zip and they would only have to open the .html file, we all know that's just not right. Now, a chrome extension is a way to distribute your game that will allow offline access. I will not cover this right now but here's a very simple [tutorial](https://developer.chrome.com/webstore/get_started_simple) --- # Release > Release — Monogatari documentation. Source: https://monogatari.io/v1/release Section: Documentation v1 Browse the Release guides: - [Chrome App](/v1/release/chrome) - [Desktop App](/v1/release/desktop) - [Mobile](/v1/release/mobile) - [Web](/v1/release/web) --- # Ren'py Source: https://monogatari.io/v1/port/renpy Section: Documentation v1 If you already have a Ren'py game and would like to export it to Monogatari, you can do it very easily. As you may have seen the syntax is pretty much the same so you'll only need to change some letters, add some commas and you'll be ready to go! You can take a look to the script of The Question in [Ren'py](http://www.renpy.org/doc/html/thequestion.html) and [Monogatari](https://datadyne.perfectdark.space/monogatari/community/samples/The%20Question.zip) Scripts so you can compare and learn more! --- # Port > Port — Monogatari documentation. Source: https://monogatari.io/v1/port Section: Documentation v1 Browse the Port guides: - [Ren'py](/v1/port/renpy) --- # Image Menus Source: https://monogatari.io/v1/design/image-menus Section: Documentation v1 Many use Image Menus for their interfaces, however, I really discourage this in Monogatari. It's fairly easy to do it as you can see in [this tutorial](http://www.w3schools.com/tags/tag_map.asp) however using image maps is not good for the responsiveness and since we want everyone to be able to enjoy our game, I really encourage you to do everything using HTML and CSS. Sure, the buttons, headers, texts etc. can have background images, but try to avoid using them as the main interface. --- # Icons Source: https://monogatari.io/v1/design/icons Section: Documentation v1 Icons are very useful, specially for a game, Font Awesome is included in Monogatari and as you can see from below, they sure have a lot of icons that you can use! To learn more about how to use them, visit their [webpage](http://fortawesome.github.io/Font-Awesome/). --- # HTML Data Attributes Source: https://monogatari.io/v1/design/data-attributes Section: Documentation v1 ### Understanding all the Datas If you've already seen the HTML, you'll notice many "data" attributes in the elements; this are used by the engine so you may change the structure and using the right datas everything will just work. This table will resume the general datas and what are they for. | Data | Function | | :--- | :--- | | data-action | All data-actions well... do something, they are handled by the $$"\[data-action\]"$.click function in the engine. | | data-ui | The data-uis are part of the user interface, things that the user will see. | | data-component | The data-uis are part of the user interface, however the user will not see them. | | data-menu | The data-menus are the screens and menus of your game. | | data-background | Put an image url on it and it will apply that image as a background to that element. | | data-close | Closes another element by it's data-ui name. | | data-target | This is mainly used for internal functions, just to target the specific media player. | | data-string | Used for Multilanguage Games, will change the text of the element with the proper translation from the strings.js file. | | data-jump | Used in choices, to state what a choice will do when it's clicked. | Now, that gives you some idea of what everything is for, now you need to understand what every one of them is used for. | Data | Function | | :--- | :--- | | data-action="open-menu" | Opens the menu/screen from the data-open next to it and closes the others. | | data-action="back" | While playing, it will go back to the previous statement, while on a menu, it will just go back to the main screen. | | data-action="close" | Will trigger the close of an element, using the data-close next to it. | | data-action="close-video" | Closes the Video element. | | data-action="set-language" | Used for the language setting. | | data-action="set-volume" | Changes the volume of the element given in the data-target next to it. | | data-action="jump" | Declares an element that when clicked will make the game jump to the label declared inside it's data-jump. | | data-jump="\[label\]" | Declares the label the game will jump to when this data-action="jump" element is clicked. | | data-component="modal" | Defines a modal window like the one used for the messages. | | data-ui="inner-menu" | Defines a menu inside another menu/screen. | | data-ui="slots" | Defines the place where the save and load slots will be displayed. | | data-ui="text" | Defines the place where the "Say" text and character's name is displayed. | | data-ui="who" | Defines the place where the character's name is displayed. | | data-ui="say" | Defines the place where the "Say" text is displayed. | --- # CSS Classes Source: https://monogatari.io/v1/design/classes Section: Documentation v1 There are already some CSS classes declared, to make your designing a little easier. As you may have already noticed, many are already being used in the basic interface you get by default. | Class | Description | | :--- | :--- | | center | Positions the element in the horizontal center of the screen. | | left | Positions the element in the left side of the screen. | | right | Positions the element in the right side of the screen. | | bottom | Positions the element in the bottom of the screen. | | middle | Positions the element in the middle of the screen, vertically and horizontally. | | align-left | Aligns the content to the left. | | align-center | Aligns the content to the center. | | align-right | Aligns the content to the right. | | vertical | Distributes the content vertically. | | horizontal | Distributes the content horizontally. | | dark | It will change the letter color to a darker color. It must be placed in the quick-menu element for games with light backgrounds. | | light | It will change the letter color to a lighter color. Must be placed in the body for games with dark backgrounds. | --- # Design > Design — Monogatari documentation. Source: https://monogatari.io/v1/design Section: Documentation v1 Browse the Design guides: - [CSS Classes](/v1/design/classes) - [HTML Data Attributes](/v1/design/data-attributes) - [Icons](/v1/design/icons) - [Image Menus](/v1/design/image-menus) --- # Skip Main Menu Source: https://monogatari.io/v1/configuration/skip-menu Section: Documentation v1 You may not want to have a main menu, in order for the game to start right away after the user enters. To do that, just change the `"ShowMenu"` property in the `options.js` file This property default value is `true` meaning it will show the Main menu. ```javascript "ShowMenu": true ``` To skip it, just change the value to `false`: ```javascript "ShowMenu": false ``` --- # Saving Source: https://monogatari.io/v1/configuration/saving Section: Documentation v1 ### Multiple Games in the same domain. You may have multiple games in the same domain, if you keep the default save name in all of them, you'll notice they'll share the save and load slots. That's why, you can change the name prefix of the save slots in the options.js file, just change the value of the `engine["SaveLabel"]` variable. ```javascript "SaveLabel": "Save" ``` ### Change Number of Auto Save Slots You can easily increase or decrease the number of save slots available for your game. Simply go to the options.js file and change the `engine["Slots"]` value to any number you want. ```javascript "Slots": 0 ``` ### Auto Saving You can make your game have autosaves every certain time, to do so, just change in the options.js file the "AutoSave" property. By default, this property is set to 0, meaning AutoSaving is off. ```javascript "AutoSave": 0 ``` You can change this number to the number of every minutes you want your game to be autosaved. For example, the following will autosave the game every 5 minutes: ```javascript "AutoSave": 5 ``` You can also change the AutoSave Labels Name, to do so change the "AutoSaveLabel" property in the options.js file. --- # Internationalization Source: https://monogatari.io/v1/configuration/internationalization Section: Documentation v1 You can create a multi-language Game also pretty easily. To do so you need to do 4 simple things: 1. Go to the options.js file and change the `engine["MultiLanguage"]` value to true. 2. Change your script. The default Script looks like this: ```javascript var script = { "Start":[ "Hi, welcome to your first Visual Novel with Monogatari." ] } ``` Your new Multi Language script will have language labels that look like this: ```javascript var script = { "English":{ "Start":[ "Hi, welcome to your first Visual Novel with Monogatari." ] }, "Español":{ "Start":[ "Hola, bienvenido a tu primer Novela Visual con Monogatari." ] } } ``` 1. Add translations to the strings.js file for your Interface. 2. Finally, add your language options to the select element in the settings page of your HTML. ```markup <select data-action="set-language"> <option value="English">English</option> <option value="Español">Español</option> </select> ``` The value attribute of each option has to match the language labels available. You can write on pretty much every language available for the web, so there's no limitation! --- # Asset Preloading Source: https://monogatari.io/v1/configuration/asset-preloading Section: Documentation v1 When releasing your game online, the asset loading is one of the most important issues to be solved, it must be nice enough so that people can enjoy playing your game online even on slow connections and that's why since v1.3.2 Asset Preloading is built in right in the engine. #### Built In Preloading The asset preloading will show a progress bar when you enter the game, the entire preloading can be disabled using the `Preload` property in the options.js: This property default value is true meaning it will show the Preload Screen and do all the Asset Preloading ```javascript "Preload": true ``` To skip it, just change the value to false but remember that every asset will be loaded when you use it and may make a poor experience for users on slow connections. ```javascript "Preload": false ``` #### Service Workers Cache One of the benefits the Service Workers in Monogatari provide is the use of the Cache to serve your files even when offline once they've been loaded, this means that instead of taking the asset from the network, Monogatari will first check if the asset has been loaded in the cache, if it has then it will inmediatly load it from there but still making a network request to update the asset in the cache. This means the users will see the asset load instantly and will still receive the updates you make. More details about this strategy are [available here](https://serviceworke.rs/strategy-cache-and-update_service-worker_doc.html) and [here](https://css-tricks.com/serviceworker-for-offline/). This functionality is inside the `service-worker.js` file. There you'll need to take notice of the three properties: `name`, `version` and `files`. The `name` and `version` properties are used to control the cache of your game, change the `name` to your game's name, whith no spaces or special characters and the `version` property as a control. ```javascript // The name of your game, no spaces or special characters. var name = 'Monogatari'; // The version of the cache, changing this will force everything to be cached // again. var version = '0.1.0'; ``` What does using the `version` as a control means? Well, lets take a look at the `files` variable first, this array defines all the files you want to store in the cache, by default this just caches files that most likely won't change nad it's up to you to add your game assets and other files: ```javascript var files = [ // General Files '/', 'manifest.json', // HTML Files // 'index.html', // CSS Files 'style/animate.min.css', 'style/csshake.min.css', 'style/font-awesome.min.css', 'style/normalize.min.css', // 'style/monogatari.css', // 'style/main.css', // JavaScript Files 'js/particles.min.js', 'js/jquery.min.js', 'js/artemis.min.js', 'js/plugins.js', // js/monogatari.js', // js/strings.js', // js/options.js', // js/script.js', // Fonts 'fonts/FontAwesome.otf', 'fonts/fontawesome-webfont.eot', 'fonts/fontawesome-webfont.svg', 'fonts/fontawesome-webfont.ttf', 'fonts/fontawesome-webfont.woff', 'fonts/fontawesome-webfont.woff2', // App Images 'img/favicon.ico', // Scene Images //'img/scenes/', // Character Images //'img/characters/', // Side Images //'img/characters/', // UI Images //'img/ui/', // Music Audio // 'audio/music/', // Voice Audio // 'audio/voice/' // Sound Audio // 'audio/sound/' ]; ``` If you were to leave it like that, offline playing would not be possible because you are not caching your assets such as images and audio, more importantly you can notice how important files like the monogatari.js files are commented out in that code, this is mainly to ease your development and prevent you having cache problems but for deployment, you should uncomment those out and add your own assets files as well. Let's take a look at how this variable looks like for the [demo in the website](https://monogatari.io/demo/): ```javascript var files = [ '/', 'manifest.json', // HTML Files 'index.html', // CSS Files 'style/animate.min.css', 'style/csshake.min.css', 'style/font-awesome.min.css', 'style/normalize.min.css', 'style/monogatari.css', 'style/main.css', // JavaScript Files 'js/particles.min.js', 'js/jquery.min.js', 'js/artemis.min.js', 'js/plugins.js', 'js/monogatari.js', 'js/options.js', 'js/strings.js', 'js/script.js', // Fonts 'fonts/FontAwesome.otf', 'fonts/fontawesome-webfont.eot', 'fonts/fontawesome-webfont.svg', 'fonts/fontawesome-webfont.ttf', 'fonts/fontawesome-webfont.woff', 'fonts/fontawesome-webfont.woff2', // Scene Images 'img/scenes/classroom.jpg', 'img/scenes/home.png', 'img/scenes/library.png', 'img/scenes/room.jpg', 'img/scenes/sea.jpg', // Character Images 'img/characters/Evelyn/ahahahah.png', 'img/characters/Evelyn/hehehehe.png', 'img/characters/Evelyn/hmph!.png', 'img/characters/Evelyn/ngggg....png', 'img/characters/Evelyn/normal.png', 'img/characters/Evelyn/tongue.png', 'img/characters/Evelyn/uhh.png', 'img/characters/Evelyn/wink.png', // UI Images 'img/ui/main-screen.svg' ]; ``` You can see how the core files were uncommented, the used images were added as well as the sound file. The video file used inside the demo could also be cached but it was decided not to just to save up space. By caching all the assets of the demo, you can play it even offline once you've loaded the assets once! Back to the `version` variable, changing the version will force all the assets to re-cache, useful specially when you make significant changes to them but remember that the cache strategy used will update your files eventually without the need of changing this version. Also the version does not need to be changed when removing/adding files to the cache. Most of the times you won't need to change it at all. This makes part of the effort to transform Monogatari games deployed online into full [Progressive Web Apps](https://en.wikipedia.org/wiki/Progressive_web_app) which provides a lot of benefits. You can read more about what you need to do and what that means for your players in the [Web Deployment Section](/v1/release/web) Use of Service Workers can also be disabled from the `options.js` file using the "ServiceWorkers" property. This property default value is true meaning it will make use of Service Workers to cache your assets, Service Workers may be used for other activities in the future as well, disabling this option will disable them all. ```javascript "ServiceWorkers": true ``` To disable it, just change it to false but remember that every asset will be loaded when you use it and may make a poor experience for users on slow connections. ```javascript "ServiceWorkers": false ``` It's important to note that Service Workers are only available through HTTP or HTTPS protocols, meaning they will only be available when serving your game through a server. If you just open the files on the browser, you'll see an URL that starts with `file://` and then in the console you'll find an error that says: `Failed to register a ServiceWorker: The URL protocol of the current origin ('null') is not supported.` Or, if using a newer Monogatari version, a warning that says: `Service Workers are available only when serving your files through a server, once you upload your game this warning will go away. You can also try using a simple server like this one for development: https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb/` Either way is completely normal, as soon as you upload your game online to make it playable, that message will go away on it's own. --- # Configuration > Configuration — Monogatari documentation. Source: https://monogatari.io/v1/configuration Section: Documentation v1 Browse the Configuration guides: - [Asset Preloading](/v1/configuration/asset-preloading) - [Internationalization](/v1/configuration/internationalization) - [Saving](/v1/configuration/saving) - [Skip Main Menu](/v1/configuration/skip-menu) --- # Getting Started Source: https://monogatari.io/v1/welcome Section: Documentation v1 > [!WARNING] > If you are looking for the documentation of the v2.x.x $Latest or Nightly$ release, [click here](/v2). The first thing about Monogatari that you should probably know is that with it, your visual novel is a web page first and a game later. That means that Monogatari has been created specifically for the web, putting things like responsiveness $the fact that your game will adapt to any screen or device size$ first. You don't necessarily need to think of your game this way as well, but you'll certainly take the most out of Monogatari if you do. #### Set up your environment To develop in Monogatari you would need the same as to develop a webpage, you just need a text editor capable of editing HTML, JavaScript and CSS, which means that pretty much any text editor should work, even Windows NotePad but to make it easier, you probably want one with code syntax highlighting. Some recommended $and free$ ones include: * [Atom](https://atom.io/) * [Brackets](http://brackets.io/) * [Visual Studio Code](https://code.visualstudio.com) Take a look at them and pick the one you like the most and feel comfortable with, this will be your main tool from now on. Now, you can always open a website by just clicking the file $index.html$ and opening it with your browser, however there are small aspects of Monogatari that work better when served through a web server. You don't need anything fancy for this, in fact there's a perfectly fine web server you can [download from the Chrome Store](https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb) As previously mentioned, the use of a web server is completely optional, you can just open your game with the browser as a file and it will run just fine, the web server will allow you to test features such as the Service Workers, needed for Monogatari's offline support and asset preloading. #### Download the latest release Once you've got your environment set up, it's time to download Monogatari. You can get the last release from [here](https://github.com/Monogatari/Monogatari/releases/latest). Download the .zip file and unzip it, inside you'll find your game files, now, what are those files and what are they used for? #### Directories You'll find some directories, here is what you should use them for. | Directory | Contains | | :--- | :--- | | audio | Audio files $Music, voice and sounds$. | | error | Custom error pages, you may modify those as you wish. | | fonts | Font Awesome by default,every other font should be placed here as well | | style | CSS files for your project $CSS defines the look and style of your game$. | | img | All the images for your project $UI, Backgrounds, characters etc.$ | | js | All the things that'll make your VN work | Root Directory Inside the main directory you'll find some pretty useful files. \| Directory \| Contains \| \| index.html \| This is your main file, open this file in a browser and there's your game! \| \| electron.js \| File used as an entry point for electron in case you are using it to make your game for the desktop. \| \| service-worker.js \| This file defines your service worker, used for asset preloading and caching. \| More about what to do and how to use this specific files will come later as you read the documentation. JS Directory JavaScript is the programming language you'll be using in Monogatari, it is what makes all your game work. In general, you'll be using the marked files, the files with a ˋ.min.jsˋ extension are third party libraries used for the engine and other functionality, you should leave them untouched. | File | Contains | | :--- | :--- | | main.js | If you want to add more JavaScript, this is the file to do it! | | options.js | Initial settings of your game and engine settings. | | script.js | The main script of your game. $Here's where your story, characters, images etc are declared$ | | strings.js | UI translations used for internationalization. | | monogatari.js | The engine itself, you may modify it but only if you know what you're doing. | | artemis.min.js | Aegis JavaScript library for DOM manipulation used in the engine. | | jquery.min.js | jQuery library for user defined functionality. | | particles.min.js | Javascript library for particles animations. | | typed.min.js | Javascript library for the text typing animation. | Style Directory CSS is the markup language used to style your game, from setting colors to improving the appearance, CSS is what will allow you do them all. As before, you are you'll be using the marked files, the files with a ˋ.min.cssˋ extension are third party libraries used for the engine and other functionality, you should leave them untouched. | File | Contains | | :--- | :--- | | main.css | Add your styling in this file. | | monogatari.css | File with the initial styling of Monogatari, any midifications should be done in the main.css file. | | csshake.min.css | CSS Shake Animations Library. | | animate.min.css | CSS Animations Library. | | font-awesome.min.css | CSS of Font Awesome. | | normalize.min.css | CSS Normalizer | #### Workflow Ok so now you have the environment set up, you have some idea on what the files you got are for so how can you start developing your game? 1. Try the game first, open the index.html file inside the directory you just unzipped and play the sample game through. 2. Once you've played it once, open the directory $the one you unzipped$ with the editor you chose to start making changes. 3. Open the script.js file with your editor, find the variable called ˋscriptˋ, as you'll see, all the dialogs you just saw are just a simple list in there. More information can be found in [the documentation](/v1/script/text). 4. Change one of the dialogs, save the file and reload the game $just like you reload a website$. 5. Play it again and you'll see the dialog changed just like you made it. 6. Now try adding more dialog to it and you'll quickly get how things are done. 7. Once you've gotten yourself used to adding dialogs, [add a scene](/v1/script/scenes) as a challenge, that means you'll have to add your image file to the ˋimg/scenes/ directoryˋ, more instructions are on the link. If you manage to do all that, congratulations! You just made your first game and are probably more familiarized with the workflow you'll be using, just make changes, save, reload, try and repeat! #### Getting Help While this documentation covers many parts of Monogatari's functioning, it does not cover everything you could actually do with it, remember, your VN is a website now and that means the possibilities are endless. Everything you've seen on a website before can be done in your game. But how to look out for help on doing this things? Well, another benefit of your game being a website is: There is lots and lots of tutorials and documentation out there! If you google something, for example if you want something to happen when someone clicks an image, you can google it as "JavaScript click image", there's no need to look for a Monogatari-specific answer, everything that applies to a website also applies for Monogatari, even the step-by-step tutorials on web development are useful to get you started. But of course, you are not alone! If you have any doubt, problem or just want some help please contact me, I'll be glad to help in any way I can. Even though Monogatari is simple enough and you can find many resources online, I know it can be hard to get started and sometimes the documentation is not clear enough, so really, contact me anytime! You can join the [Discord server](https://discord.gg/sj4uPrP) or contact me through [Mastodon](https://mastodon.social/@HyuchiaDiego) as well! If you like Monogatari and would like to support it's creation you can do so by supporting me via [Patreon](https://www.patreon.com/Hyuchia), you can even get the personalized support reward for Monogatari $which is something I do for free if you contact me as previously mentioned but making a pledge through Patreon shows your support and really helps the project :$ \)

Past Sponsors

Contributors

Features

Simple Syntax

Multimedia Support

Multi-language

Feature Full

Customizable

Responsive

Progressive Web App

Open Source

Multi-platform

Get Involved

Built on Open Source

Sponsor

Not what you're looking for?

Ren'Py

TyranoScript

RenJS

Thanks for downloading!

Select your language

Help

Quick Menu

Keyboard Shortcuts

Gallery

Want to see your name here?

Past Sponsors

Contributors

Features

Simple Syntax

Multimedia Support

Multi-language

Feature Full

Customizable

Responsive

Progressive Web App

Open Source

Multi-platform

Get Involved

Built on Open Source

Sponsor

Not what you're looking for?

Ren'Py

TyranoScript

RenJS

Select your language

Help

Quick Menu

Keyboard Shortcuts

Gallery

Help