{"id":18387821,"url":"https://github.com/dhowe/dialogic","last_synced_at":"2025-04-07T01:31:23.803Z","repository":{"id":40910193,"uuid":"115245807","full_name":"dhowe/dialogic","owner":"dhowe","description":"Dialogic: generative interactive dialog","archived":false,"fork":false,"pushed_at":"2022-12-08T04:29:59.000Z","size":31816,"stargazers_count":27,"open_issues_count":35,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-22T10:23:40.208Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhowe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-24T06:54:26.000Z","updated_at":"2024-09-13T19:59:37.000Z","dependencies_parsed_at":"2023-01-24T10:30:21.075Z","dependency_job_id":null,"html_url":"https://github.com/dhowe/dialogic","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhowe%2Fdialogic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhowe%2Fdialogic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhowe%2Fdialogic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhowe%2Fdialogic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhowe","download_url":"https://codeload.github.com/dhowe/dialogic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247577872,"owners_count":20961191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T01:28:08.629Z","updated_at":"2025-04-07T01:31:19.600Z","avatar_url":"https://github.com/dhowe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Dialogic :fish:\n\n[![Build Status](https://travis-ci.org/dhowe/dialogic.svg?branch=master)](https://travis-ci.org/dhowe/dialogic) ![license](https://img.shields.io/badge/license-GPL-orange.svg) [![Gitter](https://badges.gitter.im/dhowe/dialogic.svg)](https://gitter.im/dhowe/dialogic?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=body_badge)\n\nCheck out [Tendar](https://tenderclaws.info/sheet.php?p=tendar), the award-winning augmented reality game using Dialogic on your Android device. Here's a [review](https://variety.com/2018/digital/news/tender-claws-tendar-ar-game-1203029351/)...\n\n\u003chr/\u003e\n\n[FAQ](https://github.com/dhowe/dialogic/wiki) \u0026nbsp;::\u0026nbsp; [Command Reference](https://github.com/dhowe/dialogic/wiki/Command-Reference) \u0026nbsp;::\u0026nbsp; [API Docs](http://rednoise.org/dialogic-api/) \u0026nbsp;::\u0026nbsp; [Workbench](http://rednoise.org/dialogic/editor/) \u0026nbsp;::\u0026nbsp; [NuGet Package](https://www.nuget.org/packages/org.rednoise.dialogic/)\n\nDialogic is a system designed to help writers easily create interactive scripts with generative elements. It enables writers to craft compelling dialog that responds organically both to user prompts and to events in the environment. The system supports arbitrarily complex interactions between multiple actors, but makes no assumptions about how text is displayed, or about how users will choose their responses. These tasks are left to game designers and programmers (using tools like Unity).\n\n\n\nEach section of text in a Dialogic script is known as a [CHAT](https://github.com/dhowe/dialogic/wiki/Command-Reference#chat). Each chat has a unique name and contains one or more commands. When a chat is run, each command is executed in order, until all have been run, or the system branches to a new chat. \n\nThe simplest command is [SAY](https://github.com/dhowe/dialogic/wiki/Commands#say) which simply echoes the given output:\n\n````\nSAY Welcome to your first Dialogic script!\n````\n\nBecause the system is designed for handling text, no quotations are needed around strings. In fact, the SAY keyword itself is even optional. So the simplest Dialogic script is just a single line of text:\n\n````\nWelcome to your first Dialogic script!\n````\n\n\u0026nbsp;\n\n### Basic Commands\n\nCommands generally begin a line. Common commands include [SAY](https://github.com/dhowe/dialogic/wiki/Command-Reference#say), [DO](https://github.com/dhowe/dialogic/wiki/Command-Reference#do), [ASK](https://github.com/dhowe/dialogic/wiki/Command-Reference#ask), [OPT](https://github.com/dhowe/dialogic/wiki/Command-Reference#opt), [FIND](https://github.com/dhowe/dialogic/wiki/Command-Reference#find), [SET](https://github.com/dhowe/dialogic/wiki/Command-Reference#set), and [others](https://github.com/dhowe/dialogic/wiki/Command-Reference)\n\nHere is a short example:\n\n````\nCHAT Start\nSAY Welcome to my world\nWAIT 1.2\nSAY Thanks for Visiting\nASK Do you want to play a game?\nOPT Sure\nOPT No Thanks\n````\n\nThis script is called \"Start\" and performs a few simple functions; welcoming a visitor, pausing, then prompting for a response. \n\nOf course in most cases we would want to _do something_ with this response. \n\nIn the code below we _branch_, based on the user's response:\n\n````\nASK Do you want to play a game?\nOPT Sure #Game1\nOPT No Thanks\n````\n\nIf the user selects the first option, Dialogic jumps to the chat named \"Game1\". If not, the current chat continues.\n\n\n\n### Generative Elements\n\nDialogic is designed to smoothly blend scripted and generated text to create the type of variation found in natural-sounding dialog. The simplest way to blend generative elements into a response is via the OR operator (the pipe | character), grouped with parentheses as follows:\n\n```\nSAY You look (sad | gloomy | depressed).\n```\n\nElements between the | operators are randomly selected, so the line above will generate each of the following 3 outputs with equal probability:\n\n\n```\nYou look sad.\nYou look gloomy.\nYou look depressed.\n```\n\n\nWriters may also specify weightings for various choices, as well as favoring choices that have not been recently selected. Another example, demonstrating nested OR constructions:\n\n````\nSAY I'm (very | super | really) glad to ((meet | know) you | learn about you).\n````\n\n\u0026nbsp;\n\nYou can also save the results of an expansion for later use. For example, lets say that you wanted to pick a character name to be reused several times in a paragraph. You could do the following:\n\n````\nSAY Once there was a girl called [hero=(Jane | Mary)].\nSAY $hero lived in [home=(Neverland | Nowhereland)].\nSAY $hero liked living in $home.\n````\n\nOutputs would include:\n\n````\nOnce there was a girl called Jane.\nJane lived in Neverland.\nJane liked living in Neverland.\n````\n\nOR\n\n````\nOnce there was a girl called Mary.\nMary lived in Nowhereland.\nMary liked living in Nowhereland.\n````\n\nYou could also use the [SET](https://github.com/dhowe/dialogic/wiki/Command-Reference#set) command to similar effect:\n\n````\nSET hero = (Jane | Mary)\nSET home = (Neverland | Nowhereland)\nSAY Once there was a girl called $hero\nSAY $hero lived in $home.\nSAY $hero liked living in $home.\n````\n\n\n\n### Transforms\n\nDialogic also supports _transformation functions_ (called transforms) for modifying the results of expanded symbols and groups. Built-in transforms include Pluralize(), Articlize(), and [others](http://rednoise.org/dialogic/class_dialogic_1_1_transforms.html), which can be called from scripts as follows:\n\n````\nASK How many (tooth | menu | child).Pluralize() do you have?\n````\n\nwhich will result in one of the following: \n\n````\nHow many teeth do you have?\nHow many menus do you have?\nHow many children do you have?\n````\n\nOR \n\n````\nSAY Are you (dog | cat | ant).Articlize()?\n````\n\nwhich gives: \n\n````\nAre you a dog?\nAre you a cat?\nAre you an ant?\n````\n\nYou can also use transforms on variables:\n````\nSET choices = (tooth | menu | child)\nASK How many $choices.Pluralize() do you have?\n````\n\nOr on parenthesized words or phrases\n````\nASK How many (octopus).Pluralize() do you have?\n````\n\nYou can also use built-in C# string functions:\n````\nSET choices = (tooth | menu | child)\nASK How many $choices.ToUpper() do you have?\n````\n\nOr arbitrarily chain multiple transforms:\n````\nSET choices = (tooth | menu | child)\nASK How many $choices.Pluralize().ToUpper() do you have?\n````\n\n\n\u0026nbsp;\n\nCoders can also add custom transforms as follows, which can then be called from Dialogic scripts:\n\n```\nchatRuntime.AddTransform(\"MyTrans\", MyTransform);\n```\n\nTransform functions should be static functions that take and return a string, as follows:\n\n````\npublic static string MyTransform(string str) { ... }\n````\n\n\n\n\n### Interruption / Smoothing\n\nDialogic is also designed to respond naturally to user interaction and/or interruption. This is enabled primarily via a stack abstraction in which new CHATS are added at top. When an event or other interruption occurs, the response CHAT is pushed atop the stack and the current CHAT marked as 'interrupted'. When the response CHAT is finished, control moves to the next interrupted chat on the stack. Smoothing sections can be added in order to make transitions more natural, i.e., 'so as I was saying'.\n\nTo add smoothing to a Chat, use the 'onResume' metadata tag, specifying either the label of the smoothing Chat, or a set of FIND constraints to use in locating it. In the example below, each time the 'Long' Chat is interrupted, 'Smooth2' will be triggered before it resumes once again.\n\n````\nCHAT Long {onResume=Smooth2}\nSAY Oh, it's you...\nSAY It's been a long time. How have you been?\n...\n...\nSAY You get what I'm saying?\n\n\nCHAT Smooth2 {noStart=true}\nSAY Where was I? Oh, yes\n````\n\n\n\n\n### Special Characters\nAs in most scripting languages, certain characters have special meaning in Dialogic scripts. These include the following: !, #, }, {, \", =, etc. If you need to use these characters in your scripts, you can use [HTML entities](https://dev.w3.org/html5/html-author/charref), which will be replaced in Dialogic's output. This also applies to leading and trailing spaces and multiple consecutive spaces, for which you can use the `\u0026nbsp;` entity.\n\n````\nCHAT TestSpecial\nSAY \u0026num; is usually a label\n````\nwhich will output: \n\n````\n# is usually a label\n````\n\n\n\n### Integrating Dialogic\n\nDialogic can be run alone or with a game engine, such as Unity3D (see example below). The system includes two main components: the scripting language described above, and the runtime environment, which is responsible for passing events between the runtime and the application. \n\nIn the C# example below, a [_ChatRuntime_](http://rednoise.org/dialogic/class_dialogic_1_1_chat_runtime.html) is created that reads in chat descriptions from a plain-text file (or folder) and compiles them into a list of _Chat_ objects. The runtime's Run() function is called to start execution, specifying the Chat to run first.\n\nThe application calls the runtime's Update() function each frame, passing the current world-state (a dictionary of key-value pairs) and any event that occurred during that frame. If a Dialogic event occurs during the frame, it is returned from the Update function.\n````C#\n\n public RealtimeGame() \n {\n    dialogic = new ChatRuntime();\n    dialogic.ParseFile(fileOrFolder);\n    dialogic.Run(\"#StartChat\");\n }\n\n public IUpdateEvent Update() // Game Loop\n {\n     // Call the dialogic interface\n     IUpdateEvent evt = dialogic.Update(worldState, ref gameEvent);\n\n     // Handle the event received\n     if (evt != null) HandleEvent(evt);\n     \n     ...\n }\n````\n\n\n\n\n### Serialization\nThe Dialogic system can be paused and resumed, with state saved to a file or an array of bytes. The specific serialization package is up to you (we generally use [MessagePack](https://github.com/neuecc/MessagePack-CSharp), but other options can be used, as long as they  implement the [ISerializer](http://rednoise.org/dialogic/interface_dialogic_1_1_i_serializer.html) interface.) In the example below, current state is saved to a file, then reloaded into a new ChatRuntime.\n\n```C#\n\n// Create a runtime and load it with Chats\nChatRuntime rt1 = new ChatRuntime();\nrt1.ParseFile(fileOrFolder);\n\n// Now serialize its state to a file\nFileInfo saveFile = new FileInfo(\"./runtime.ser\");\nISerializer serializer = new SerializerMessagePack();\ntmp.Save(serializer, saveFile);\n\n// Now load it from the file and continue\nChatRuntime rt2 = ChatRuntime.Create(serializer, saveFile);\nrt2.Run();\n\n```\n\n\n\n\u0026nbsp;\n\n### Building Dialogic with Visual Studio\n\n1. Clone this respository to your local file system ```` $ git clone https://github.com/dhowe/dialogic.git````\n\n1. From Visual Studio, do Menu-\u003eFile-\u003eOpen, then select dialogic.sln from the top-level of the cloned dir\n\n1. The solution should open with 3-4 sub-projects, as in the image below. \n\n1. To run the tests, right-click 'tests' and select 'Run Item'\n\n![](http://rednoise.org/images/vsloaded.png?raw=true)\n\n\n\n\u0026nbsp;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhowe%2Fdialogic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhowe%2Fdialogic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhowe%2Fdialogic/lists"}