diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 278ec82..095e732 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -5,6 +5,8 @@ - [Character & Portraits](characters-and-portraits.md) - [Styles & Layouts](styles-and-layouts.md) +- [Variables](variables.md) +- [Timeline Text Syntax](timeline-text-syntax.md) - [Dialogic Nodes](dialogic-nodes.md) - [Dialogic Signals](dialogic-signals.md) - [Custom Portraits](custom-portraits.md) diff --git a/documentation/media/headers/translations.png b/documentation/media/headers/translations.png new file mode 100644 index 0000000..51d0e98 Binary files /dev/null and b/documentation/media/headers/translations.png differ diff --git a/documentation/media/headers/variables.png b/documentation/media/headers/variables.png new file mode 100644 index 0000000..3cc1b66 Binary files /dev/null and b/documentation/media/headers/variables.png differ diff --git a/documentation/styles-and-layouts.md b/documentation/styles-and-layouts.md index cb4a72f..0df97bd 100644 --- a/documentation/styles-and-layouts.md +++ b/documentation/styles-and-layouts.md @@ -1,54 +1,79 @@ +![header_text_syntax](media/headers/styles_and_layouts.png) # Styles & Layouts -![header_style-editor](/media/headers/styles_and_layouts.png) +## Introduction -## 📜 Content +One important aspect of dialogic is how it allows you to display your timelines. To achieve this there is a number of systems working together: Dialogic Nodes, Layout Scenes and Styles. -- [1. Styles & Layouts](#1-styles--layouts) -- [2. The style editor](#2-the-style-editor) +**Dialogic Nodes** are nodes can be placed in any scene. These nodes will be activated by dialogic and do wildly different things, from displaying text, labels or choices to playing sounds or defining a clickable area. -# 1. Styles & Layouts +**Layout Scenes** are scenes that contain both Dialogic Nodes, other godot Control nodes and custom scripts and provide a standalone UI-part. For example there is a `VisualNovel Textbox Scene`, a `Glossary Popup Scene` or a `Centered Choices Scene`. -- A **style** is a combination of a layout scene (preset or custom) and a set of settings. -- A **layout** is a scene that can display dialog ingame. +**Dialogic Styles** are a resource that holds a combination of layout scenes and allows applying settings to them. This is the easiest way of modifying the look of dialogic, as styles can be edited in dialogics Style editor. -Dialogic comes with some **preset layouts**, but you can create your own using DialogicNodes. Learn more about [custom layouts here](/documentation/dialogic-nodes). +## Working with styles -![layout_presets](/media/layout_presets.png) +[You can find a video walktrough of dialogic styles here.]([Dialogic 2 - New Style System - YouTube](https://www.youtube.com/watch?v=TLnzSzqBwu4)) -*You can add more presets with extensions. Feel free to share cool layouts you've made via the [discord](https://discord.gg/2hHQzkf2pX).* +A style is made up of -# 2. The style editor +- One `Base` layout scene (of type DialogicLayoutBase) and settings for that scene. -The style editor allows you to create and edit styles. By default you only have the `Default` style that uses the VisualNovel layout. +- A list of `Layer` layout scenes (of type DialogicLayoutLayer) and settings for each layer. - +In the style editor you can -### Style list +- Add new styles (either starting empty or from a premade style) -The style list section lets you: +- Rename Styles -- add new styles -- duplicate styles -- add a new style that inherits the current one -- delete styles -- mark the current style as default +- Add/Replace/Remove layers (both premade scenes and custom scenes) -### Changing the Layout +- Set all kinds of settings on any of the scenes that are part of that style -You can change the layout the current style uses by clicking `Change` next to the layout thumbnail. This will open a layout selection page: +- Make one of the premade layers or a whole style custom - +- Make an inherited style from another style (inherits scenes and default settings) -- Select Custom will allow you to select a scene from your project -- Clicking a preset will show info about that preset and allow you to select it +- Change the default style -*If your style inherits from another style, the layout is determined by the "parent"-style and cannot be changed.* +### Using styles in game -### Inheritance +You can switch between different styles with the `Change Style` event, by calling `Dialogic.Styles.load_style()` before calling `Dialogic.start()`, or by assigning a style to a character. -You can set a style to inherit from another one. A style will inherit the layout and the settings from it's parent style. +## Custom Styles & Layouts -### Settings +You can pretty much customize any or all parts of this "Displaying" part of dialogic. -Layouts can expose settings to the editor. These can easily be changed for each style and allow customizing a style. The presets each come with different settings. +### Custom styles + +The simplest is creating a custom style, combining different layers and changing their settings. + +### Custom Layout Scenes + +The next step would be to customize part of your layout (one of the scenes) beyond what's possible with the provided settings. + +An easy way to do this is to use the "Make Custom" button above the layer list and selecting "Current Layer". This will create a copy of that layers scene which you can edit in godot. This is what you would do if you generally like e.g. the textbox, but would like to change something about it that's impossible with just the settings. + +``` +```admonish info +When editing a layout that's been made custom, be careful which sub-resources (e.g. scripts, fonts, images, etc.) might still be inside the addons/dialogic folder. If you modify these the changes might be lost when updating dialogic. I recommend making any sub-resource "unique" before modifying it. Some, like the scenes root-script however are usually made custom automatically when using "Make Custom". +``` + +``` +Alternatively you can start a custom layout scene from scratch. + +- Your scene's root node has to have a script that extends from either `DialogicLayoutBase` or `DialogicLayoutLayer` depending on your use-case. + +- In your scenes root script you can export variables which will appear as settings in dialogics style editor. Grouping them with @export_group and @export_subgroup makes it even nicer. Note that not all types are supported here. + +- If you want to utilize dialogics style system then you should apply any @exported settings in a method called `_apply_export_overrides()` which is called whenever the style changes. + +You can add your custom scene in very easily by either using `Add Layer` or `Replace Layer` above the layer list. + +### Custom nodes + +While dialogics modules usually expect the nodes that display them to be made in a certain way, that doesn't prevent you from actually customizing the nodes themselves. Each dialogic node is just a normal control node with a script attached to it. Usually dialogic nodes interact with dialogic subsystems through a group they add themselves to. + +Note that in most cases reacting to some of dialogic signals (or signals of existing dialogic nodes) can be way easier then creating a custom version of a dialogic node. +``` diff --git a/documentation/timeline-text-syntax.md b/documentation/timeline-text-syntax.md new file mode 100644 index 0000000..3709908 --- /dev/null +++ b/documentation/timeline-text-syntax.md @@ -0,0 +1,124 @@ +![header_text_syntax](media/headers/text_syntax.png) + +Timelines are saved in a text format, which means that you can use any text-editing software to edit and create them. The built in text editor provides useful autocompletion and syntax highlighting. +📜 +*Info: For dialogic to register your timeline file, it has to use the `.dtl` extension!* + +
+📜 Content + +- [About shortcode events](#about-shortcode-events) + +- [About special events](#about-special-events) + +- [About Indentation](#about-indentation) + +- [Example Timeline](#Example-timeline) + +
+ +## About shortcode events + +Most events follow a shortcodes-like style: + +``` +[background path="res://icon.png" fade="1.0"] +``` + +The order of the parameters does not matter, but they have to be separated by at least one space. All parameters regardless of type have to be contained in double quotation marks. + +To find all of the parameters you can use on each event, check out their documentation by searching for their class in the godot help or this documentation. + +## About special events + +Some events have a custom syntax, to make writing them easier. This includes: + +- Character event: + + - `join Emilio (happy) 3 [animation="Bounce In"]` + - `leave Emilio [animation="Bounce Out" length="0.3"]` + - `update Emilio (excited) 4 [animation="Tada" wait="true" repeat="3" move_time="0.3"]` + +- Text event:  + + - `A wonderful text event, said by noone in particular.` + - `Emilio (excited): Hello and welcome!` + - Ending a text event with \ will make it include the next line as well. + +- Choice event: + + - `- I don't know about that` + - `- Yes [if {John.Relationship} > 23]` + - `- Sure, I'm the great wizard [if {Stats.Charisma} > 10] [else="disable" alt_text="I'm the great wizard [to insecure]"]` + +- Condition event: + + - `if {Player.Wisdom} > 3:` + - `elif {Player.Health} <= 10:` + - `else:` + +- Set Variable event: + + - `set {MyVariable} += 10` + - Supported Operators are =, += , -= , *=, /= + +- Comment event: + + - `# Todo: Finnish this!!!!` + +- Label event: + + - `label MyLabelName` + +- Jump event: + + - `jump MyLabelName` + - `jump TimelineName/` # the slash is mandatory to clarify this is a timeline not a label + - `jump TimelineName/LabelName` + +- Return event: + + - `return` + +## About indentation + +Timelines use TAB indentation to know what events belong to a choice or condition block. Only changes in indentation are considered, so it doesn't really matter how much you indent as long as you are consistent within one block. + +## Example timeline + +``` +[background path="res://assets/backgroudns/dialogic_factory.png"] + +join Jowan 4 +jowan (exited): Hello and welcome to[portrait=confused]...[pause=0.5] Wait? What is this? + +Join Emilio (happy) 1 +Emilio: Well, this is is the example timeline. + +Jowan: I thought this was a cool new feature? + +Emilio: Nah, sorry. + +Jowan (sad): It's okay. + +# Some choices jump back to this +label WhatAbout + +Jowan (default): So what should this example be about? +- How to bake cookies +    Emilio (confused): Wait that hasn't to do with dialogic?! +    jump WhatAbout + +- How to reach the moon [if {Player.Name} == "NASA"] +    Jowan (angry): NASA! It's you again. This is for making dialogs!\ +    Please ask someone else about the moon!. +     +    jump WhatAbout + +- How to write timelines in text format +    Jowan: Oh, well it's pretty intuitive.[pause= 0.2][portrait=questioning] I hope. +     +    Emilio: Let's hope it's easy as well. + +[end_timeline] +``` diff --git a/documentation/variables.md b/documentation/variables.md new file mode 100644 index 0000000..499a249 --- /dev/null +++ b/documentation/variables.md @@ -0,0 +1,196 @@ +![header_text_syntax](media/headers/variables.png) + +# Variables + +Variables are good way to keep track of all kinds of things during your game. +Dialogic has an easy-to-use and beginner friendly variable system built in. However Dialogic allows to use outside variables (of Autoload Singletons) just as easily. +You can also access the Dialogic variables from outside scripts. + +To fully utilize these variables this page contains all you need to know. + +## 📜 Content + +- [The dialogic variable editor](##the-dialogic-variable-editor) +- [Using variables in the timeline](##using-variables-in-the-timeline) + - [Variables in texts](###Variables-in-texts) + - [Conditions](###Conditions) + - [Set Variable event](###Set-variable-event) + - [Text Input event](###Text-input-event) +- [Other uses for variables](##Using-variables-for-other-cool-stuff) +- [Using variables outside of dialogic](##Using-variables-outside-of-dialogic) + +## + +## The dialogic variable editor + +Dialogic variables can be setup in the variables editor. Each variable consists of a name and an initial default value. + +Variables can be grouped together in folders (which just have a name). + +Important: Inside a folder no item (variable or folder) can have the same name. + +## + +## Using variables in the timeline + +### Variables in texts + +In text events you can insert the value of a dialogic variable by typing `{variable_name}`. +If your dialogic variable is inside a folder (or multiple folders) you have to specify the whole name separated with dots: `{MyFolder.variable_name}` or `{FolderA.FolderB.variable_name}` + +If you want to use a variable from an Autoload write `{AutoloadName.variable}`. +This syntax also allows calling methods on that autoload. Whatever is returned from the method is inserted into the text: `{Autoload.get_random_name()}` + +You can even do simple operations inside the brackets: `{{Player.Health}/10.0+2}` + +### + +### Conditions + +One of the main uses for variables is in conditions (if & elif, or conditions on choices). + +##### Conditions: Visual Editor + +In the visual editor you can simply select the variable from the dropdown and compare it to a value of your chioce. If you need something more complex, click the `` button and use the syntax described below. + +##### Conditions: Text syntax + +In conditions you can use all the same tricks as in text events and a couple more: + +- Accessing autoloads: `Autoload.property` + + - *In conditions Autoloads don't have to wrapped in {} brackets.* + +- Using autoload methods: `Autoload.check_info("Argument", false)` + + - A conidtion always results in a boolean at the end using the same rules as gdscript for type conversion. + +- Using variables and typical boolean operators (==, !=, <, >, <=, >=, not, and, or, brackets): + + - `{Player.Health} > 5 or {Player.Luck} > randi()%10` + +### + +### Set Variable event + +You can change variables in a timeline with the set variable event. This can set dialogic variables as well as autoload variables. + +##### Set Variable: Visual Editor + +In the visual editor you can simply select a variable and a value. You can also set the value of an autoload variable by typing `Autoload.variable` in directly into the variable field and submitting with `Enter` (there is no auto-completion). + +The value that it will be set to can be a + +- string, + +- number (float or int), + +- value of another variable, + +- complex expression, + +- random number + +**Complex Expression** allows you to use the full range of possibilities. Behind the scenes all of these types are an expression, the distinction is only done for a simpler UI. Expressions follow the syntax described below. + +##### Set Variable: Text syntax + +The set variable event has a special syntax to make it easy to write and read: + +```gdscript +set {variable_name} = 20 + +set {MyFolder.variable} += 2 + +set Autoload.property = "Hello World" + +set {Player.Health} += range(10,20).pick_random() + +set Autoload.health = {Player.Health} + 2 +``` + +The value is parsed as an expression similar to what is done with {expressions} inside text events or in conditions. All the same can be done here as well, the only difference is that it won't be converted to string/bool. + +### + +### Text Input event + +A special kind of set variable event is the `Text Input` event which allows you to capture a text input the player makes in a variable. + +## + +## Using variables for other cool stuff + +#### Variables as character names + +A characters `Display Name` can be a variable. That is the best way to control that characters name during the game. To achieve this just type `{MyVariableName}` in the display name field in the character editor. + +#### Variables in glossaries + +You can use variables in glossaries titles, texts and extras. This is the best way to control the texts during the game. You can do all the same things as in the text event. + +## + +## Using variables outside of dialogic + +You might want to access variables from scripts outside of dialogic. + +You can do so like a direct access: + +```gdscript +Dialogic.VAR.my_variable = 20 +print(Dialogic.VAR.Group.other_variable) +``` + +You can also do so by string: + +```gdscript +Dialogic.VAR.set('my_variable', 20) +print(Dialogic.VAR.get('Group').get('my_variable')) +``` + +Folders (as well as the root "folder") have some methods that might be useful: + +- `folders()` lists all folders in this folder (not strings but FolderObjects) + +- `variables(@absolute)` lists the names of all the variables in that folder + +- `has(@variable_name)` returns true if such a variable exists + +This allows you to do fancy stuff like this: + +```gdscript +var location = Dialogic.VAR.Towns.folders().pick_random().variables().pick_random() +``` + +Could pick a random house/place if your variables are setup like this: + +``` +Towns (folder) + +   - Town A (folder) + +     - CharacterAHouse + +     - CharacterBHouse + +     - Church + +     - School + +  - Town B (folder) + +     - CharacterCHouse + +     - CharacterDHouse + +     - University + +     - Park +``` + +Dialogic.VAR also has: + +- `Dialogic.VAR.reset(@variable_path="")` resets the given variable or all variables if none is specified + +- `Dialogic.VAR.parse_variables(@string)` returns the given string with variables replaced. This is what is used by the text event, etc.