{"id":13663316,"url":"https://github.com/ashblue/fluid-dialogue","last_synced_at":"2025-04-08T18:18:17.261Z","repository":{"id":41773954,"uuid":"191786280","full_name":"ashblue/fluid-dialogue","owner":"ashblue","description":"A Unity dialogue system that features an easy to use drag and drop graph. ScriptableObject driven with the ability to write custom actions and conditions to create complex dialogue workflows.","archived":false,"fork":false,"pushed_at":"2024-11-09T04:02:46.000Z","size":1028,"stargazers_count":203,"open_issues_count":3,"forks_count":16,"subscribers_count":8,"default_branch":"develop","last_synced_at":"2025-04-01T17:17:09.276Z","etag":null,"topics":["dialogue","dialogue-systems","scriptableobject","unity-package-manager","unity3d","unity3d-plugin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashblue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ashblue","patreon":null,"open_collective":null,"ko_fi":"ashblue","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-06-13T15:13:35.000Z","updated_at":"2025-03-21T04:15:20.000Z","dependencies_parsed_at":"2024-01-06T14:56:40.073Z","dependency_job_id":"7ff4bdbf-3608-4814-b371-37eb8cfb961c","html_url":"https://github.com/ashblue/fluid-dialogue","commit_stats":{"total_commits":182,"total_committers":4,"mean_commits":45.5,"dds":"0.15934065934065933","last_synced_commit":"6b48530bb195996f15bb2702bd0765aa6f676d7c"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Ffluid-dialogue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Ffluid-dialogue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Ffluid-dialogue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Ffluid-dialogue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashblue","download_url":"https://codeload.github.com/ashblue/fluid-dialogue/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247898519,"owners_count":21014722,"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":["dialogue","dialogue-systems","scriptableobject","unity-package-manager","unity3d","unity3d-plugin"],"created_at":"2024-08-02T05:02:24.248Z","updated_at":"2025-04-08T18:18:17.233Z","avatar_url":"https://github.com/ashblue.png","language":"C#","funding_links":["https://github.com/sponsors/ashblue","https://ko-fi.com/ashblue"],"categories":["C\\#","C#"],"sub_categories":[],"readme":"# Fluid Dialogue\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nA Unity dialogue system that features an easy to use drag and drop graph. ScriptableObject driven with the ability to write custom actions and conditions to create complex dialogue workflows.\n\n* **Visual graph** editor\n* Ability to create custom **actions** that execute as dialogue progresses\n* Create custom **conditions** to determine how dialogue branches\n* Built in **local database** to set and check variables for branching\n* Allows you to **bring your own UI** or use a starter example (event driven dialogue presentation)\n* Includes a simple [spell check](https://github.com/ashblue/unity-simple-spellcheck) tool that evaluates all dialogue nodes\n\n![](docs/example-dialogue.png)\n\n**Support**\n\nJoin the [Discord Community](https://discord.gg/8QHFfzn) if you have questions or need help.\n\nSee upcoming features and development progress on the [Trello Board](https://trello.com/b/wMrsWyxn/fluid-dialogue).\n\n## Getting Started\n\nFirst you'll need to [install](#installation) the package with Unity Package Manager. After that you can create a database as follows.\n\n1. Right click on the project window\n1. Create -\u003e Fluid -\u003e Dialogue -\u003e Graph\n1. Click \"Edit Dialogue\" to customize your graph\n\nTo create a custom UI to display your graph, you'll need to handle a series of events emitted by the dialogue controller. You can find a full example of this in the [Examples](#examples) folder.\n\n### Playing Dialogue\n\nTo trigger dialogue playback you'll need the following snippet. This will turn your dialogue data into an ongoing conversation with events and variables.\n\n```csharp\nusing System.Collections;\nusing System.Linq;\nusing CleverCrow.Fluid.Databases;\nusing CleverCrow.Fluid.Dialogues.Graphs;\nusing CleverCrow.Fluid.Dialogues;\nusing UnityEngine;\n\npublic class ExampleDialoguePlayback : MonoBehaviour {\n  private DialogueController _ctrl;\n  public DialogueGraph dialogue;\n  \n  private void Awake () {\n    var database = new DatabaseInstanceExtended();\n    _ctrl = new DialogueController(database);\n    _ctrl.Events.Speak.AddListener((actor, text) =\u003e { Debug.Log($\"{actor.DisplayName}: {text}\"); });\n    _ctrl.Play(dialogue);\n  }\n}\n```\n\nFor more details see the [`ExampleDialoguePlayback.cs`](https://github.com/ashblue/fluid-dialogue/blob/develop/Assets/Examples/BasicConversation/Scripts/ExampleDialoguePlayback.cs) file for a complete solution on how to manage dialogue in your game.\n\n### Node Types\n\nThere are a few different node types. Each with a specific focus in mind.\n\n* Dialogue: Choices and text from a specific actor\n* Hub: Used to route dialogue logic without triggering any dialogue or choices\n* Choice Hub: Used to trigger a set of choices multiple times\n\n### Actors\n\nEvery dialogue should have an actor assigned to it. Actors can be created with the following steps.\n\n1. Right click on the project window\n1. Create -\u003e Fluid -\u003e Dialogue -\u003e Actor\n\n### Actions\n\nActions can be added after selecting a node. They can be triggered before a node activates (enter actions) or after a node is complete (exit actions). Note that actions can activate with a delay.\n\n### Conditions\n\nConditions are just like actions. Except if any of them return false the node will be skipped at runtime until it's evaluated again.\n\n### Local Variables\n\nTo create a local variable and use it do the following.\n\n1. Right click on the project window\n1. Create -\u003e Fluid -\u003e Database -\u003e Choose a variable type\n\nTo use the variable simply select a node on the graph. Then click the plus sign on a condition (variable checks) or action (change variable value) in the inspector. Please note you must assign the variable you just created to use it.\n\n### Global Variables\n\nGlobals are mostly the same as local variables. The difference is these will be saved to a global database that persists after the conversation is over and can be referenced across multiple conversations.\n\nThe GlobalDatabaseManager will be marked DoNotDestroyOnLoad to persist between scene loads. If you want to save it and write the contents to a file run `Save()` to return a string. You can then restore the database simply by calling `Load(returned save string)`.\n\n### Interacting With Runtime GameObject(s)\n\nTo interact with GameObject(s) at runtime use the \"SendMessage\" action suite. You cannot directly reference GameObjects in the dialogue graph as they are separately serialized. Instead, you can use the \"SendMessage\" action to send a message to a GameObject at runtime.\n\nIt's strongly recommended when sending messages you use a consistent object name like \"DIALOGUE_DIRECTOR\" to keep things simple and write your own custom scripts to handle the messages. This will make it easier to maintain and debug your game.\n\n![send-message.png](docs/send-message.png)\n\nYou can also use the \"SetActive\" action to toggle GameObjects on and off. This is a great low overhead way to manage dialogue scripts easily.\n\nIf you need to do a lot of heavy lifting with tons of scripting on runtime GameObjects, it's recommended you write your own custom actions to handle this. See the APIs section for more details.\n\n### Examples\n\nTo see the entire Fluid Dialogue workflow, it's highly recommended that you download this repo and run projects in the `Assets/Examples` folder.\n\n## Installation\n\nFluid Dialogue is used through [Unity's Package Manager](https://docs.unity3d.com/Manual/CustomPackages.html). In order to use it you'll need to add the following lines to your `Packages/manifest.json` file. After that you'll be able to visually control what specific version of Fluid Dialogue you're using from the package manager window in Unity. This has to be done so your Unity editor can connect to NPM's package registry.\n\n```json\n{\n  \"scopedRegistries\": [\n    {\n      \"name\": \"NPM\",\n      \"url\": \"https://registry.npmjs.org\",\n      \"scopes\": [\n        \"com.fluid\"\n      ]\n    }\n  ],\n  \"dependencies\": {\n    \"com.fluid.dialogue\": \"2.6.0\"\n  }\n}\n```\n\n## APIs\n\nThe following APIs are available for customizing your dialogue experience.\n\n### Custom Actions\n\nYou can create your own custom actions for the dialogue tree with the following API syntax.\n\n```c#\nusing CleverCrow.Fluid.Dialogues.Actions;\nusing CleverCrow.Fluid.Dialogues;\n\n[CreateMenu(\"Custom/My Action\")]\npublic class CustomAction : ActionDataBase {\n    public override void OnInit (IDialogueController dialogue) {\n        // Run the first time the action is triggered\n    }\n\n    public override void OnStart () {\n        // Runs when the action begins triggering\n    }\n\n    public override ActionStatus OnUpdate () {\n        // Runs when the action begins triggering\n\n        // Return continue to span multiple frames\n        return ActionStatus.Success;\n    }\n\n    public override void OnExit () {\n        // Runs when the actions `OnUpdate()` returns `ActionStatus.Success`\n    }\n\n    public override void OnReset () {\n        // Runs after a node has fully run through the start, update, and exit cycle\n    }\n}\n```\n\n### Custom Conditions\n\nCustom conditions can be crafted with the following API.\n\n```c#\nusing CleverCrow.Fluid.Dialogues;\nusing CleverCrow.Fluid.Dialogues.Conditions;\nusing CleverCrow.Fluid.Dialogues.Nodes;\n\npublic class CustomCondition : ConditionDataBase {\n    public override void OnInit (IDialogueController dialogue) {\n        // Triggered on first time setup\n    }\n\n    public override bool OnGetIsValid (INode parent) {\n        // Place node condition logic here\n        return true;\n    }\n}\n```\n\n### Resuming Graph Playback\n\nGraph playback can be resumed from anywhere. This includes nested graphs and the exact node you want to resume from.\n\n```C#\nvar ctrl = new DialogueController(...);\n\n// Play your graph to generate runtime data and advance the graph to a specific node by hand\nctrl.Play(...);\n\n// Record the required serialized properties\nvar graph = ctrl.RootGraph; // Finds the root graph that is playing\nvar parentHierarchy = dialogue.Ctrl.ParentHierarchy; // Gets the IDs of all nodes the nested graphs that are playing\nvar nextNodeId = ctrl.ActiveDialogue.Pointer.Next()?.UniqueId; // You probably want the next node in your graph, not the current one\n\n// Create a new graph and resume playback\nvar newCtrl = new DialogueController(...);\n\nif (newCtrl.CanPlay(graph, parentHierarchy, nextNodeId)) {\n    // Failsafe that makes sure our graph playback data is valid    \n    newCtrl.Play(graph, parentHierarchy, nextNodeId);\n} else {\n    // If the data is invalid, just play the graph from the beginning or implement your own fallback logic\n    newCtrl.Play(graph);\n}\n```\n\n### Custom Nodes (Experimental)\n\nYou can create your own custom nodes with the following API. Please note this is experimental and missing some features.\n\nFirst you will need to setup the data layer. This is what will be converted to a nested ScriptableObject on demand for the graph.\n\n```c#\nusing System.Linq;\nusing CleverCrow.Fluid.Dialogues;\nusing CleverCrow.Fluid.Dialogues.Graphs;\nusing CleverCrow.Fluid.Dialogues.Nodes;\n\nnamespace YourNamespaceHere {\n    // Changing this will customize the name in the graph editor creation menu\n    [CreateMenu(\"Example\")]\n    public class NodeExampleData : NodeDataBase {\n        public string myMessage;\n        \n        // This is the default name the node will display in the graph editor\n        protected override string DefaultName =\u003e \"Example\";\n        \n        public override INode GetRuntime (IGraph graphRuntime, IDialogueController dialogue) {\n            return new NodeCombat(\n                graphRuntime,\n                UniqueId,\n                myMessage,\n                children.ToList\u003cINodeData\u003e(),\n                conditions.Select(c =\u003e c.GetRuntime(graphRuntime, dialogue)).ToList(),\n                enterActions.Select(c =\u003e c.GetRuntime(graphRuntime, dialogue)).ToList(),\n                exitActions.Select(c =\u003e c.GetRuntime(graphRuntime, dialogue)).ToList()\n            );\n        }\n    }\n}\n```\n\nNext you will need to create the runtime node. This is what will be generated at runtime for every corresponding data object.\n\n```c#\nusing CleverCrow.Fluid.Dialogues;\nusing CleverCrow.Fluid.Dialogues.Graphs;\nusing CleverCrow.Fluid.Dialogues.Nodes;\n\nnamespace YourNamespaceHere {\n    public class NodeExample : NodeBase {\n        readonly string _myMessage;\n\n        public NodeCombat (\n            IGraph runtime,\n            string uniqueId,\n            // We've added our new value here. You can pass in whatever values you need. Just add more parameters to the constructor\n            string myMessage,\n            System.Collections.Generic.List\u003cINodeData\u003e children,\n            System.Collections.Generic.List\u003cFluid.Dialogues.Conditions.ICondition\u003e conditions,\n            System.Collections.Generic.List\u003cFluid.Dialogues.Actions.IAction\u003e enterActions,\n            System.Collections.Generic.List\u003cFluid.Dialogues.Actions.IAction\u003e exitActions)\n            // This is what handles all the messy setup we'd normally have to do\n            : base(runtime, uniqueId, children, conditions, enterActions, exitActions) {\n            \n            _myMessage = myMessage;\n        }\n        \n        // Handles what happens when the node is played\n        protected override void OnPlay (IDialoguePlayback playback) {\n            Debug.Log(_myMessage);\n        }\n    }\n}\n```\n\nLastly you will need to create a view layer. This is what will be displayed in the graph editor. Please note this must be nested in a folder called `Editor`.\n\n```c#\nusing CleverCrow.Fluid.Dialogues.Editors;\nusing CleverCrow.Fluid.Dialogues.Editors.NodeDisplays;\nusing UnityEditor;\nusing UnityEngine;\n\nnamespace YourNamespaceHere {\n    [NodeType(typeof(NodeExampleData))]\n    public class NodeExampleEditor : NodeEditorBase {\n        protected override Color NodeColor { get; } = new(0.75f, 0.52f, 0f);\n        protected override float NodeWidth =\u003e 200;\n\n        protected override void OnPrintBody (Event e) {\n            serializedObject.Update();\n            \n            // This creates a dynamic input for the myMessage field\n            EditorGUILayout.PropertyField(serializedObject.FindProperty(\"myMessage\"), GUIContent.none);\n            \n            serializedObject.ApplyModifiedProperties();\n        }\n    }\n}\n```\n\nAnd that's it. The node will now be available in the graph editor and print our message at runtime. It even supports conditions, actions, and parent/child connections.\n\nFor more details please take a look at the source code for the different node types. This will give you a better idea of how to structure more complex custom nodes with multiple choices and other details.\n\n## Releases\n\nPlease note that whatever node you're resuming from will play that exact node with enter actions and all previous nodes will not trigger anything. This is a direct reference and does not simulate the graph from the beginning.\n\n```c#\n\n## Releases\n\nArchives of specific versions and release notes are available on the [releases page](https://github.com/ashblue/fluid-dialogue/releases).\n\n## Nightly Builds\n\nTo access nightly builds of the `develop` branch that are package manager friendly, you'll need to manually edit your `Packages/manifest.json` as so. \n\n```json\n{\n    \"dependencies\": {\n      \"com.fluid.dialogue\": \"https://github.com/ashblue/fluid-dialogue.git#nightly\"\n    }\n}\n```\n\nNote that to get a newer nightly build you must delete this line and any related lock data in the manifest, let Unity rebuild, then add it back. As Unity locks the commit hash for Git urls as packages.\n\n## Development Environment\n\nIf you wish to run to run the development environment you'll need to install the latest [node.js](https://nodejs.org/en/). Then run the following from the root once.\n\n`npm install`\n\nIf you wish to create a build run `npm run build` from the root and it will populate the `dist` folder.\n\n### Making Commits\n\nAll commits should be made using [Commitizen](https://github.com/commitizen/cz-cli) (which is automatically installed when running `npm install`). Commits are automatically compiled to version numbers on release so this is very important. PRs that don't have Commitizen based commits will be rejected.\n\nTo make a commit type the following into a terminal from the root\n\n```bash\nnpm run commit\n```\n\n---\n\nThis project was generated with [Oyster Package Generator](https://github.com/ashblue/oyster-package-generator).\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/bosaku\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/2468343?v=4?s=100\" width=\"100px;\" alt=\"Richard Bryan Irwin\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRichard Bryan Irwin\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ashblue/fluid-dialogue/commits?author=bosaku\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashblue%2Ffluid-dialogue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashblue%2Ffluid-dialogue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashblue%2Ffluid-dialogue/lists"}