From e50531c214231249e67c6f2d385f584ed37c8e60 Mon Sep 17 00:00:00 2001 From: Jowan <42868150+Jowan-Spooner@users.noreply.github.com> Date: Fri, 16 Aug 2024 14:43:38 +0200 Subject: [PATCH] Add text effects and modifiers pages (#59) --- documentation/SUMMARY.md | 217 +++++++++++++-------------- documentation/text-effects.md | 127 ++++++++++++++++ documentation/text-modifiers.md | 91 +++++++++++ documentation/writing-text-events.md | 132 ---------------- documentation/writing-texts.md | 29 ++++ 5 files changed, 355 insertions(+), 241 deletions(-) create mode 100644 documentation/text-effects.md create mode 100644 documentation/text-modifiers.md delete mode 100644 documentation/writing-text-events.md create mode 100644 documentation/writing-texts.md diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index a1463aa..49fbb87 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -1,24 +1,23 @@ # 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) @@ -26,113 +25,113 @@ - [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) \ No newline at end of file diff --git a/documentation/text-effects.md b/documentation/text-effects.md new file mode 100644 index 0000000..10685ab --- /dev/null +++ b/documentation/text-effects.md @@ -0,0 +1,127 @@ +
+ +*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). diff --git a/documentation/text-modifiers.md b/documentation/text-modifiers.md new file mode 100644 index 0000000..bf7c944 --- /dev/null +++ b/documentation/text-modifiers.md @@ -0,0 +1,91 @@ + + +*Text modifiers are text-preprocessors, that means before the text is shown a method is run on it and changes the texts contents. Many text modifiers come with a special syntax that you'll have to use.* + +*Most text modifiers work in text events AND in choice events, but not all.* + +## 📜 Content + +[TOC] + +## Line Break + +**Syntax:** `[br]` + +**Supports:** *Text Events, Choice Events* + +This effect inserts a line break. This can be useful in choices (where you can't add a real line break) or when using the "New Lines as New events" setting and wanting to insert a line break that doesn't trigger a new event. + +--- + +## Random selection + +**Syntax:** `