Add text effects and modifiers pages (#59)

Author: Jowan-Spooner

documentation/SUMMARY.md

@@ -1,138 +1,137 @@
 # Summary
 
-[Introduction](introduction.md)
+- [Introduction](introduction.md)
     - [Getting Started](getting-started.md)
 
-[FAQ](faq.md)
+- [FAQ](faq.md)
 
 - [Character & Portraits](characters-and-portraits.md)
-
   - [Custom Portraits](custom-portraits.md)
   - [Layered Portraits](layered-portraits.md)
 
 - [Styles & Layouts](styles-and-layouts.md)
-
   - [Dialogic Nodes](dialogic-nodes.md)
 
+- [Writing Texts](writing-texts.md)
+  - [Text Effects](text-effects.md)
+  - [Text Modifiers](text-modifiers.md)
+ 
 - [Variables](variables.md)
-
 - [Timelines]()
-
-  - [Writing Text Events](./writing-text-events.md)
   - [Timeline Text Syntax](timeline-text-syntax.md)
   - [Creating Timelines In Code](creating-timelines-in-code.md)
 
 - [Events]()
   - [Character Event](event-character.md)
 
 - [Input]()
-
+  
   - [Auto-Advance](auto-advance.md)
   - [Auto-Skip](auto-skip.md)
 
 - [Utilities]()
-    - [Dialogic Signals](dialogic-signals.md)
-    - [Pausing](pausing.md)
-    - [Saving & Loading](saving-and-loading.md)
-    - [Reference Manager](reference-manager.md)
-    - [Creating Extensions](creating-extensions.md)
-    - [Glossary](glossary.md)
-    - [Translations](translation.md)
+  - [Dialogic Signals](dialogic-signals.md)
+  - [Pausing](pausing.md)
+  - [Saving & Loading](saving-and-loading.md)
+  - [Reference Manager](reference-manager.md)
+  - [Creating Extensions](creating-extensions.md)
+  - [Glossary](glossary.md)
+  - [Translations](translation.md)
 
 - [Class Reference](class_index.md)
-    - [Event](event_class_index.md)
-        - [BackgroundEvent](classes/class_dialogicbackgroundevent.md)
-        - [CallEvent](classes/class_dialogiccallevent.md)
-        - [CharacterEvent](classes/class_dialogiccharacterevent.md)
-        - [ChoiceEvent](classes/class_dialogicchoiceevent.md)
-        - [CommentEvent](classes/class_dialogiccommentevent.md)
-        - [ConditionEvent](classes/class_dialogicconditionevent.md)
-        - [EndBranchEvent](classes/class_dialogicendbranchevent.md)
-        - [EndTimelineEvent](classes/class_dialogicendtimelineevent.md)
-        - [Event](classes/class_dialogicevent.md)
-        - [GlossaryEvent](classes/class_dialogicglossaryevent.md)
-        - [HistoryEvent](classes/class_dialogichistoryevent.md)
-        - [JumpEvent](classes/class_dialogicjumpevent.md)
-        - [LabelEvent](classes/class_dialogiclabelevent.md)
-        - [DialogiClearEvent](classes/class_dialogiclearevent.md)
-        - [MusicEvent](classes/class_dialogicmusicevent.md)
-        - [PositionEvent](classes/class_dialogicpositionevent.md)
-        - [ReturnEvent](classes/class_dialogicreturnevent.md)
-        - [SaveEvent](classes/class_dialogicsaveevent.md)
-        - [SettingEvent](classes/class_dialogicsettingevent.md)
-        - [SignalEvent](classes/class_dialogicsignalevent.md)
-        - [SoundEvent](classes/class_dialogicsoundevent.md)
-        - [StyleEvent](classes/class_dialogicstyleevent.md)
-        - [TextEvent](classes/class_dialogictextevent.md)
-        - [TextInputEvent](classes/class_dialogictextinputevent.md)
-        - [VariableEvent](classes/class_dialogicvariableevent.md)
-        - [VoiceEvent](classes/class_dialogicvoiceevent.md)
-        - [WaitEvent](classes/class_dialogicwaitevent.md)
-        - [WaitInputEvent](classes/class_dialogicwaitinputevent.md)
-
-    - [Subsystem](subsystem_class_index.md)
-        - [Audio](classes/subsystem_audio.md)
-        - [Backgrounds](classes/subsystem_backgrounds.md)
-        - [Portraits](classes/subsystem_portraits.md)
-        - [Choices](classes/subsystem_choices.md)
-        - [Animation](classes/subsystem_animation.md)
-        - [Expression](classes/subsystem_expression.md)
-        - [Input](classes/subsystem_input.md)
-        - [Glossary](classes/subsystem_glossary.md)
-        - [History](classes/subsystem_history.md)
-        - [Jump](classes/subsystem_jump.md)
-        - [Save](classes/subsystem_save.md)
-        - [Settings](classes/subsystem_settings.md)
-        - [Styles](classes/subsystem_styles.md)
-        - [Text](classes/subsystem_text.md)
-        - [Text Input](classes/subsystem_text_input.md)
-        - [Variables](classes/subsystem_variables.md)
-        - [Voice](classes/subsystem_voice.md)
-
-    - [Node](node_class_index.md)
-        - [Node_BackgroundHolder](classes/class_dialogicnode_backgroundholder.md)
-        - [Node_ButtonSound](classes/class_dialogicnode_buttonsound.md)
-        - [Node_ChoiceButton](classes/class_dialogicnode_choicebutton.md)
-        - [Node_DialogText](classes/class_dialogicnode_dialogtext.md)
-        - [Node_Input](classes/class_dialogicnode_input.md)
-        - [Node_NameLabel](classes/class_dialogicnode_namelabel.md)
-        - [Node_PortraitContainer](classes/class_dialogicnode_portraitcontainer.md)
-        - [Node_StyleLayer](classes/class_dialogicnode_stylelayer.md)
-        - [Node_TextBubble](classes/class_dialogicnode_textbubble.md)
-        - [Node_TextInput](classes/class_dialogicnode_textinput.md)
-        - [Node_TypeSounds](classes/class_dialogicnode_typesounds.md)
-
-    - [Resource](resource_class_index.md)
-        - [Character](classes/class_dialogiccharacter.md)
-        - [CharacterFormatLoader](classes/class_dialogiccharacterformatloader.md)
-        - [CharacterFormatSaver](classes/class_dialogiccharacterformatsaver.md)
-        - [Glossary](classes/class_dialogicglossary.md)
-        - [Style](classes/class_dialogicstyle.md)
-        - [StyleLayer](classes/class_dialogicstylelayer.md)
-        - [Timeline](classes/class_dialogictimeline.md)
-        - [TimelineFormatLoader](classes/class_dialogictimelineformatloader.md)
-        - [TimelineFormatSaver](classes/class_dialogictimelineformatsaver.md)
-
-    - [Other](other_class_index.md)
-        - [DCSS](classes/class_dcss.md)
-        - [Animation](classes/class_dialogicanimation.md)
-        - [AutoAdvance](classes/class_dialogicautoadvance.md)
-        - [AutoSkip](classes/class_dialogicautoskip.md)
-        - [Background](classes/class_dialogicbackground.md)
-        - [BackgroundTransition](classes/class_dialogicbackgroundtransition.md)
-        - [CharacterEditorMainSection](classes/class_dialogiccharactereditormainsection.md)
-        - [CharacterEditorPortraitSection](classes/class_dialogiccharactereditorportraitsection.md)
-        - [CsvFile](classes/class_dialogiccsvfile.md)
-        - [Editor](classes/class_dialogiceditor.md)
-        - [GameHandler](classes/class_dialogicgamehandler.md)
-        - [Indexer](classes/class_dialogicindexer.md)
-        - [LayoutBase](classes/class_dialogiclayoutbase.md)
-        - [LayoutLayer](classes/class_dialogiclayoutlayer.md)
-        - [Portrait](classes/class_dialogicportrait.md)
-        - [ResourceUtil](classes/class_dialogicresourceutil.md)
-        - [SettingsPage](classes/class_dialogicsettingspage.md)
-        - [Subsystem](classes/class_dialogicsubsystem.md)
-        - [Util](classes/class_dialogicutil.md)
-        - [VisualEditorField](classes/class_dialogicvisualeditorfield.md)
+  - [Event](event_class_index.md)
+    - [BackgroundEvent](classes/class_dialogicbackgroundevent.md)
+    - [CallEvent](classes/class_dialogiccallevent.md)
+    - [CharacterEvent](classes/class_dialogiccharacterevent.md)
+    - [ChoiceEvent](classes/class_dialogicchoiceevent.md)
+    - [CommentEvent](classes/class_dialogiccommentevent.md)
+    - [ConditionEvent](classes/class_dialogicconditionevent.md)
+    - [EndBranchEvent](classes/class_dialogicendbranchevent.md)
+    - [EndTimelineEvent](classes/class_dialogicendtimelineevent.md)
+    - [Event](classes/class_dialogicevent.md)
+    - [GlossaryEvent](classes/class_dialogicglossaryevent.md)
+    - [HistoryEvent](classes/class_dialogichistoryevent.md)
+    - [JumpEvent](classes/class_dialogicjumpevent.md)
+    - [LabelEvent](classes/class_dialogiclabelevent.md)
+    - [DialogiClearEvent](classes/class_dialogiclearevent.md)
+    - [MusicEvent](classes/class_dialogicmusicevent.md)
+    - [PositionEvent](classes/class_dialogicpositionevent.md)
+    - [ReturnEvent](classes/class_dialogicreturnevent.md)
+    - [SaveEvent](classes/class_dialogicsaveevent.md)
+    - [SettingEvent](classes/class_dialogicsettingevent.md)
+    - [SignalEvent](classes/class_dialogicsignalevent.md)
+    - [SoundEvent](classes/class_dialogicsoundevent.md)
+    - [StyleEvent](classes/class_dialogicstyleevent.md)
+    - [TextEvent](classes/class_dialogictextevent.md)
+    - [TextInputEvent](classes/class_dialogictextinputevent.md)
+    - [VariableEvent](classes/class_dialogicvariableevent.md)
+    - [VoiceEvent](classes/class_dialogicvoiceevent.md)
+    - [WaitEvent](classes/class_dialogicwaitevent.md)
+    - [WaitInputEvent](classes/class_dialogicwaitinputevent.md)
+  
+  - [Subsystem](subsystem_class_index.md)
+    - [Audio](classes/subsystem_audio.md)
+    - [Backgrounds](classes/subsystem_backgrounds.md)
+    - [Portraits](classes/subsystem_portraits.md)
+    - [Choices](classes/subsystem_choices.md)
+    - [Animation](classes/subsystem_animation.md)
+    - [Expression](classes/subsystem_expression.md)
+    - [Input](classes/subsystem_input.md)
+    - [Glossary](classes/subsystem_glossary.md)
+    - [History](classes/subsystem_history.md)
+    - [Jump](classes/subsystem_jump.md)
+    - [Save](classes/subsystem_save.md)
+    - [Settings](classes/subsystem_settings.md)
+    - [Styles](classes/subsystem_styles.md)
+    - [Text](classes/subsystem_text.md)
+    - [Text Input](classes/subsystem_text_input.md)
+    - [Variables](classes/subsystem_variables.md)
+    - [Voice](classes/subsystem_voice.md)
+  
+  - [Node](node_class_index.md)
+    - [Node_BackgroundHolder](classes/class_dialogicnode_backgroundholder.md)
+    - [Node_ButtonSound](classes/class_dialogicnode_buttonsound.md)
+    - [Node_ChoiceButton](classes/class_dialogicnode_choicebutton.md)
+    - [Node_DialogText](classes/class_dialogicnode_dialogtext.md)
+    - [Node_Input](classes/class_dialogicnode_input.md)
+    - [Node_NameLabel](classes/class_dialogicnode_namelabel.md)
+    - [Node_PortraitContainer](classes/class_dialogicnode_portraitcontainer.md)
+    - [Node_StyleLayer](classes/class_dialogicnode_stylelayer.md)
+    - [Node_TextBubble](classes/class_dialogicnode_textbubble.md)
+    - [Node_TextInput](classes/class_dialogicnode_textinput.md)
+    - [Node_TypeSounds](classes/class_dialogicnode_typesounds.md)
+  
+  - [Resource](resource_class_index.md)
+    - [Character](classes/class_dialogiccharacter.md)
+    - [CharacterFormatLoader](classes/class_dialogiccharacterformatloader.md)
+    - [CharacterFormatSaver](classes/class_dialogiccharacterformatsaver.md)
+    - [Glossary](classes/class_dialogicglossary.md)
+    - [Style](classes/class_dialogicstyle.md)
+    - [StyleLayer](classes/class_dialogicstylelayer.md)
+    - [Timeline](classes/class_dialogictimeline.md)
+    - [TimelineFormatLoader](classes/class_dialogictimelineformatloader.md)
+    - [TimelineFormatSaver](classes/class_dialogictimelineformatsaver.md)
+  
+  - [Other](other_class_index.md)
+    - [DCSS](classes/class_dcss.md)
+    - [Animation](classes/class_dialogicanimation.md)
+    - [AutoAdvance](classes/class_dialogicautoadvance.md)
+    - [AutoSkip](classes/class_dialogicautoskip.md)
+    - [Background](classes/class_dialogicbackground.md)
+    - [BackgroundTransition](classes/class_dialogicbackgroundtransition.md)
+    - [CharacterEditorMainSection](classes/class_dialogiccharactereditormainsection.md)
+    - [CharacterEditorPortraitSection](classes/class_dialogiccharactereditorportraitsection.md)
+    - [CsvFile](classes/class_dialogiccsvfile.md)
+    - [Editor](classes/class_dialogiceditor.md)
+    - [GameHandler](classes/class_dialogicgamehandler.md)
+    - [Indexer](classes/class_dialogicindexer.md)
+    - [LayoutBase](classes/class_dialogiclayoutbase.md)
+    - [LayoutLayer](classes/class_dialogiclayoutlayer.md)
+    - [Portrait](classes/class_dialogicportrait.md)
+    - [ResourceUtil](classes/class_dialogicresourceutil.md)
+    - [SettingsPage](classes/class_dialogicsettingspage.md)
+    - [Subsystem](classes/class_dialogicsubsystem.md)
+    - [Util](classes/class_dialogicutil.md)
+    - [VisualEditorField](classes/class_dialogicvisualeditorfield.md)
 
 [Contributing](contributing.md)

documentation/text-effects.md

@@ -0,0 +1,127 @@
+<div class="header-banner tropical">
+     <div class="header-label tropical">Text Effects</div>
+</div>
+
+*Text effects are tags that define a position in text and an action that happens, when that position is reached during the reveal of the text. Many text effects take an additional argument. They are useful to change the behaviour of the text revealing (e.g. speed, pauses, skipping, etc.) or to react to specific moments in the text (signal, changing the speakers portrait or sound mood).*
+
+## 📜 Content
+
+[TOC]
+
+## Splitting Events
+
+### Effect: New Event
+
+**Syntax:** `[n]` / `[n+]`
+
+Visually starts a new event, requiring manual advancement by the user or by the Auto-Advance system.
+
+The variant with the `+` will append the following text to the previous without clearing the text box.
+
+### Effect: Input
+
+**Syntax:** `[input]` 
+
+Will simply await any input when reached. As opposed to [n+], it is not breaking the text up into multiple sections and can thus be skipped. 
+
+---
+
+## Speeds & Pauses
+
+Text speed is a complicated topic, as it can be used in numerous ways. Dialogic has
+
+- a **letter speed** (specifies the time to wait on each symbol)
+
+- a **speed multiplier** (modifies the letter and pause speed, resets every event)
+
+- a **text speed setting** (also modifies letter and pause speed)
+
+---
+
+### Letter Speed
+
+The letter speed defines the time (in seconds) that each letter takes to be revealed. The default can be changed in the text settings. It can be changed temporarily (it will reset before the next event) with these effects:
+
+#### Effect: Setting Letter Speed
+
+**Syntax:** `[lspeed=x]` / `[lspeed]` / `[lspeed=x!]` 
+
+Sets the letter speed to x in seconds or resets to the default if no x is given. By default the speed is multiplied with both the temporary speed multiplier and the text speed setting. If you put a `!` behind the time (e.g. `[lspeed=0.1!]`) then this is not the case.
+
+---
+
+### Temporary Speed Multiplier
+
+The speed multiplier is 1 by default, so it has no effect. It can be changed temporarily (it will reset before the next event) with these effects:
+
+#### Speed Multiplier Effect
+
+**Syntax:** `[speed=x]` / `[speed]`
+
+Sets the temporary speed multiplier to x or 1 if nothing is given. As this will multiply the pause length and letter speed, a bigger number means a slower reveal, a smaller number means a faster reveal and 0 means an instant reveal.
+
+---
+
+### Pauses Effect
+
+**Syntax:** `[pause=x]` / `[pause=x!]` 
+
+Pauses the reveal for x seconds (e.g., `[pause=0.2]`). 
+
+By default this duration will be multiplied with the temporary speed multipler and the text speed setting multiplier. If you put a `!` behind the time (e.g. `[pause=0.2!]`) then this is not the case. 
+
+*Related to this are **Auto-Pauses**, which can be configured in the text settings to insert pause effects after certain symbols. This can be used to easily alter the flow of punctuation.*
+
+---
+
+### Multiplier "Text Speed" (Dialogic Setting)
+
+This is a `Dialogic Setting` so something that can be changed in-game via the Settings subsystem and is stored automatically and globally.
+
+It defaults to 1 (no effect) and can be used to add a reveal speed setting to your games option menu.
+
+You can access it via the Settings subsystem `Dialogic.Settings.text_speed = 0.5`. This should enable you to implement a speed slider in your settings
+
+---
+
+## Signal Effect
+
+**Syntax:** `[signal=arg]`
+
+Emits the `Dialogic.text_signal` signal with the given argument. Useful if you want something to happen at a specific moment during the text. Learn more about the signal: [Dialogic Signals](./dialogic-signals.md)
+
+---
+
+## Portrait & Type Sound Mood Effects
+
+### Portrait Effect
+
+**Syntax:** `[portrait=name]`
+
+Changes the portrait of the speaker to the portrait with the given name.
+
+### Type Sound Mood Effect
+
+**Syntax:** `[mood=name]`
+
+Changes the typing mood to the one with the given name.
+
+---
+
+## Auto-Advance Effect
+
+**Syntax:** `[aa]` / `[aa=x]` / `[aa=x?]`
+
+Enables the Auto-Advance for the *current* text event. 
+
+A time x (in seconds) can be given to set the Auto-Advance time. This time is absolute and overwrites the more relative "per word" or "per letter" settings. 
+
+If the time is given with a `?` then it will *only* set the time and *not* enable Auto-Advance. This is useful if the player can freely enable/disable Auto-Advance and you just want to define a different Auto-Advance time for this event, but not change it's state. 
+
+---
+
+## No Skip Effect
+
+**Syntax:** `[ns]` / `[ns=x]`
+
+This effect temporarily (for this event) disables text skipping *and* manual advance and enables Auto-Advance with the given time x (in seconds).