DefArc - Defold + Arcweave tool for branching conversations and narrative


As a continuation of Defork a new tool was born, for even more advanced, interactive dialogues:


About DefArc

DefArc is a runtime for Arcweave projects, a module helping easily create interactive branching or linear conversations or quests flow - anything you can create in Arcweave for Defold game engine.

DefArc, underneath, is a JSON parsed data and a set of helper functions to easily and conveniently create a dialogue flow in Lua. It comes with unit tests and an example Defold project. You can mix DefArc with other Defold assets like RichText or Defold Printer for text animation and displaying and Gooey or Druid for GUI handling.

DefArc is an incarnation or inheritance of my first narrative module - Defork which was used with JSON files produced by Twinson format for open-source Twine. Arcweave is not open-source, but its free plan allows you to create anything in a much more enhanced, advanced and professional environment with possibility to collaborate online on one project (2 editors for free plan). Arcweave offers also paid plans with larger limits like more editors for online collaboration on projects for larger teams. For solodevs or indie teams, it’s a great tool used by professionals like CDPR, Mojang, Microsoft, Primal, etc.


In order to use DefArc in your Defold game add it to your game.project as a Defold library dependency.

Once added, you must require the main Lua module in scripts via

local defarc = require("defarc.defarc")

Then you need to add dialogs exported from Arcweave in a JSON format to your project. To add it, you need to provide a path in Custom Resource field of your game.project in Defold.


For example, if you have your file in the dialogs folder in the project directory, type: dialogs. You can find more informations about custom resources in official Defold’s documentation here.

What you can do?

With DefArc you can easily:

  • add linear or non-linear, interactive dialogues to your games

  • utilize powerful Arcweave branching with code chunks and variables

  • load and save variables changing the flow of conversations

  • load json data exported from Arcweave conversation making tool

  • get text, options and links leading to next conversation’s nodes

  • store and manage current links, options and flow through nodes

  • modify data by adding actors, colors and custom text effects

  • add images, portraits, locations or emoticons from Arcweave assets


Arcweave allows to create complex diagrams that can be used to build linear dialogues, non-linear branching conversations with variables or quest or story flow design.

Arcweave offers a lot of options, all of them are available in free plan. Check out Arcweave features here.

Defold Example

Though DefArc offers over hundred of functions, for most games purposes, one would practically narrow the usage to just few. A simple example for handling branching dialogue in Defold is used in example project. For it to work you need to:

  1. Load the project from JSON resource:
defarc.load("/dialogs/test_board.json") -- loading Arcweave exported JSON from custom resources
  1. Select an element to start working with it, e.g. displaying the text and options.
defarc.select_element("Example welcome") -- selecting element by its title from Arcweave element
  1. Get text and options_table and put it in GUI:
local text = defarc.get_text()
	local options = defarc.get_options_table()

	gui.set_text(gui.get_node("NPC"), text) -- set text

	for i=1,3 do                            -- set 3 corresponding options
		gui.set_text(gui.get_node("Option_"..i), options[i] and options[i].label or "")

The given example runs a simple conversation, where you can choose each of the options and when reaching an end - it starts again.


To check if DefArc is working you can run a set of unit and functional tests from the example:

local defarc_test = require "defarc.defarc_test"

DefArc API

You can find the API documentation and module itself with above example and tests in my public repository (link below). The module is released with MIT license, so by leaving the license as is, you can use it however you like and in any non-comercial and commercial projects! :slight_smile:

Happy Defolding and Arcweaving! :wink:


Asset Portal:


DefArc v0.2 update!

I’ve made an update to the DefArc project! API is not changed, so still backward compatible, yet achieving a milestone - parser for HTML tags and ArcScript code inside text! I added also an example using original Arcweave example project - it has a lot of features, like checking variable condition in text, setting/saving variables (assignments) and jumpers. :slight_smile:


  • Added default HTML tags parser
  • Added default ArcScript code parser (support for the features from the Arcweave example project: if conditions, assingments, negations)
  • Added example utilizing original Arcweave example project
  • Added to this example a way to deal with Jumpers.
  • Fixed smaller bugs, refactore some parts and improved overall performance a bit

Next steps:

  • Add support for utilizing Arcweave components - display component’s image and extend examples to show such components. Perhaps make a simple visual novel example.
  • Add special HTML tag parsers in order to use parsed scripts together with Defold Printer and RichText (where syntax are slightly different)
  • Further work on ArcScript code parsing

And another update! Defarc v0.3

This time it comes with an improved, visual example based on Arcweave project and here’s the result:

I added one missing function to the API:
.get_element_assets([element]) - which returns a table of assets of the given (or selected earlier) element

Beside of this, further improvements and refactoring to the code base are added - especially that in most cases I used assert to inform users, that there is no asset or so, but better is to return false and let user’s decide what to do with this, as some elements of the json generated by Arcweave are in fact optional.


  • Addd function .get_element_assets([element]) returning assets of the element.
  • Enhanced Arcweave example with displaying images of current element’s component.
  • Added defarc.verbose flag to determine if DefArc should print or not all the warnings and informations.
  • Removed all assert checks and replaced them with returning nil, when there is no board, asset, element etc. You can now just check with all functions, if you get a desired element, not interrupting the code.
  • Fixed consistency in naming: get_notes(board) → get_board_notes(board)
  • Improved documentation.

Next steps:

  • :white_check_mark: Add support for utilizing Arcweave components - display component’s image and extend examples to show such components. Perhaps make a simple visual novel example.
  • :green_square: Add special HTML tag parsers in order to use parsed scripts with Defold Printer
  • :green_square: Add special HTML tag parsers in order to use parsed scripts with Defold RichText
  • :green_square: Further work on ArcScript code parsing