Appearance
Importing from articy:draft
Version 0.1.0 — 2026-08-27
Tarinoi imports a complete articy:draft project — its flow, its entities, its templates, its variables and its logic — into a new Tarinoi project in one pass. The import is not a viewer or a one-way preview: what lands is ordinary Tarinoi content, editable, committable, and readable by a game engine integration exactly like content authored in Tarinoi from the start.
It is also not lossless, and the parts that are not lossless are the interesting ones. articy and Tarinoi are different tools with different opinions, and a handful of articy concepts have no Tarinoi counterpart at all. This guide covers the whole journey: producing the export, running the import, reading the report it writes for you, and the finishing work that turns an imported project into one you can ship from.
Read §3 before you commit to a migration. Read §5 and §6 before you start editing.
1. Exporting from articy:draft
Tarinoi reads articy's JSON export. In articy:draft:
- Choose Export, then JSON.
- Pick the ruleset that exports the complete project, and make sure assets are included.
- Zip the folder articy produced — the whole folder, not its contents — and keep the zip.
The export folder contains a manifest.json, an object_definitions.json, a hierarchy.json, a global_variables.json, a script_methods.json, one pair of package_*_objects.json / package_*_localization.json files per package, and an Assets/ folder. Tarinoi reads all of them. An export missing the localization files produces a structurally perfect project with no words in it, which is why the ruleset matters.
This is not the Unity or Unreal export
Export → Unity and Export → Unreal produce a .unity / .articyue file. That is a proprietary binary container, not a zip, and Tarinoi cannot read it. If the file you are about to upload is not a .zip, you exported the wrong thing.
Tarinoi reads the current articy:draft X export (export version 2.x, files split as above). That is what the importer is built and tested against. The older articy:draft 3 single-document export has not been tested — if that is what you have, get in touch before planning a migration around it.
2. Running the import
In Tarinoi, New project → Import, choose articy:draft, and pick your zip.
Give the project a name and description first — these are Tarinoi's, and are not taken from the articy project.
Tarinoi then uploads and inspects the archive before importing anything. The inspection reports what it found — lines of dialogue, boards, entities — and, if the export carries more than one language, asks which one to import. Nothing has been written to your workspace at this point; you can go back and choose a different file.
Press Import. A large project takes a minute or two. When it finishes you get a summary and an Open project button.
One language per import
A Tarinoi document holds one string per property, so a multi-language articy export loses every language but the one you choose. The languages you did not pick are reported, not silently dropped.
Tarinoi's own localisation support is in design. When it lands, this is the mapping that changes — articy's per-language text will come across as localised strings rather than being narrowed to one. Until then, if you are migrating a multi-language project, import the language you author in and keep the articy export for the rest.
3. What comes across
3.1 Flow, boards and folders
An articy Dialogue or FlowFragment is a single object that is both a node in its parent's flow and a flow of its own. Tarinoi has no such thing: a board is a collection and a card is a document. So each container becomes both:
- an ordinary card where the container sat in its parent's flow, carrying the container's own template data, its entry condition and its instructions, and
- a board holding its children, reached from that card by a card link named
subflow.
The parent flow passes through the container card and on to its siblings, exactly as articy's does. The board is a linked expansion, followed by the reader rather than entered by the flow.
A sub-flow is not executed inline
articy's player descends into a container and comes back out. Tarinoi's playback does not: the flow inside the board ends at the virtual end-flow node, which is where articy handed control back. If your dialogue depends on inline descent, that structure needs rebuilding — see §6.4.
Containers that hold no flow are not boards at all. articy authors routinely use templated containers as plain data records — PDA tasks, achievements, menu entries — and an empty FlowFragment carrying template data is one of those, not a sub-flow. Those import as ordinary cards, with no board and no link.
Boards are leaves in the project tree, so nesting is expressed with folders. A container that holds sub-containers therefore becomes two collections: a folder carrying the container's name and holding its children, and inside it a board carrying the container's own cards, labelled <name> (cards).
The "(cards)" boards
This is the one piece of imported structure that has no articy counterpart and will look odd at first. Chapter 2 in articy becomes a folder Chapter 2 containing a board Chapter 2 (cards) alongside the folders for its sub-containers. The (cards) board holds exactly what was on Chapter 2's own canvas; everything else is one level down. A container with no sub-containers is a plain board, unsuffixed — there is nothing to distinguish it from.
articy UserFolders become Tarinoi folders. Only the flow hierarchy is mirrored: entities, templates, variables and lists get homes of their own, and articy's folders for them would be noise.
3.2 Cards
| articy | Tarinoi |
|---|---|
DialogueFragment | Line card. Text → the line property, Speaker → entity_ref. |
Hub | Blank card, used as a hub — the pattern the Author's Guide already recommends. |
Jump | Jump card, target resolved to the destination card. |
Jump carrying template data | Blank card with a card link named target. A Tarinoi jump holds nothing but its destination, so a jump with data stops being a jump and becomes a card that jumps. |
Comment | Annotation card — translucent, no pins, never presented. articy's Comment is a board annotation, so this needs no guesswork. |
Dialogue, FlowFragment | Blank card plus its board — see §3.1. |
| Anything else | See §3.7. |
Positions, sizes and z-order come across, scaled by a constant factor: articy's boards and Tarinoi's share units and axes but not pitch. Sizes are scaled with positions rather than snapped to Tarinoi's defaults, so a small hub stays small and a layout that did not overlap in articy does not overlap in Tarinoi.
Colours come across too. A template's colour is read from the template; where a class has no template, the colour is read from its instances. A card whose colour matches its template's is written without one, so recolouring the template afterwards recolours its cards. Cards that genuinely differ keep their own.
Icons are assigned by what the node was in articy, not by the Tarinoi card type it became — four articy classes land on blank cards, and one icon between them would waste the only glanceable signal a card list has.
3.3 Connections, pins and conditions
articy puts a condition on an input pin and an instruction on an output pin. Tarinoi agrees about conditions and not about instructions.
Conditions map straight across. A Tarinoi input pin carries a condition exactly as articy's does, which means articy's dominant branching idiom — one output pin with many connections, each target's input pin carrying the gate — needs no reshaping at all. This is the most important structural agreement between the two tools.
Instructions do not. A Tarinoi pin has no side-effect slot; the only thing a pin carries is a condition. Side effects live on the card, as properties the card's template declares with the function-call sub-type. So an articy instruction does not stay on the pin it was written on — it becomes a property of a card sitting where that instruction ran. See below.
The expressions themselves do not survive as written. A Tarinoi condition is a boolean algebra over function calls: &&, ||, !, parentheses, and nothing else. There are no comparison operators and no bare variables. So articy's Chapter1.MetTheFerryman == true becomes:
Fn.core.CheckFlag( Var.Chapter1.MetTheFerryman )CheckFlag and its siblings are ordinary function declarations that ship in Tarinoi's built-in project templates, and are imported into your project if it does not already have them. Comparisons against numbers use fused comparators — Fn.core.CounterAtLeast( Var.x, 3 ) rather than GetCounter( Var.x ) >= 3 — because Tarinoi has no >=. The rewriting is mechanical and reversible: what the condition means is unchanged, and it is your engine's implementation of CheckFlag that decides what it does.
Standalone Condition nodes have no Tarinoi equivalent — Tarinoi gates nodes, articy gates edges. The importer pushes the condition onto the successor's input pin where that is sound, and inserts a small gate card between the condition and the successor where it is not. A gate card carries the branch condition and forwards unconditionally.
Instructions, both those on output pins and standalone Instruction nodes, become function-call properties on a card: a template property of sub-type function-call holding Fn.core.SetFlag( Var.Chapter1.Flag ). A multi-statement instruction lands in an array property whose elements are calls, evaluated in order. The card sits in the flow where the instruction ran, so the ordering articy expressed is preserved — as a node in the graph rather than as a pin annotation.
Connection labels and per-connection colours are dropped. A connection targeting a specific named input pin is resolved to the target card instead; this only differs where a node has more than one input pin, which is rare.
3.4 Entities, speakers and avatars
articy entities become Tarinoi entities, under generated entity templates matching their articy templates. Speaker attribution comes across intact — DialogueFragment.Speaker is a real field in articy and is reliably populated.
Any entity used as a speaker is marked dialogue-capable.
Entities are grouped by the articy folder they sit in, one collection per template. A Tarinoi entity collection creates every one of its members from a single template, and articy folders mix templates freely — Dracula's Characters folder holds three Characters and a Merchant. Such a folder becomes one collection per template in it, named for both: Characters (Character) and Characters (Merchant). A folder holding one template keeps its own name. Entities articy filed in no folder at all are grouped into entities, or, where they span several templates, into one collection per template named after the template.
Every imported entity and card carries its articy id as an articy_id property, so the objects in your project can be joined back to the export they came from.
The player character is a guess, because articy has no field for it and every project encodes it differently. Tarinoi tries, in order: a boolean template property whose name contains "player" or "playable"; a template whose name contains "Player"; and failing both, the speaker with the most lines. Which rule fired is reported. Check it — see §6.2.
PreviewImage on an entity becomes that entity's avatar, re-encoded to the 320×320 image a Tarinoi avatar holds. PreviewImage on a dialogue or flow fragment becomes a media card on that node's board — Tarinoi's mood-board image, which is the closest thing articy has.
MenuText and StageDirections become ordinary template properties. Tarinoi has no separate slot for player-facing choice text as distinct from spoken text, and staging content is outside Tarinoi's scope by design. The data is there and your engine can read it; Tarinoi's playback and word counts do not know what it means.
3.5 Templates, features and properties
One Tarinoi template per articy template. articy's features — named property bundles, reusable across templates — are flattened into Tarinoi's single flat property list, named Feature_Property to stay collision-proof. The grouping is lost; the properties are not.
| articy property type | Tarinoi |
|---|---|
Bool | boolean |
Int | number — Tarinoi has one numeric type, so the integer constraint is not preserved |
Float | number |
ArticyString, ArticyMultiLanguageString | string |
Enum (Sex, CameraAngle, a custom enumeration…) | A list, with a list-reference property. Enum values become option keys, display names become labels. |
Id (object reference) | An entity-reference or card-link property, decided from the values actually present |
Array | array, element type inferred from the data |
Script_Condition | A condition property — or a variable-reference, where every value is in fact just a variable name, which is how the type is most often used |
Script_Instruction | A function-call property |
An articy null object reference imports as an unset reference rather than a broken one.
Enum values are resolved, not copied. An articy enum value is a number; a Tarinoi list reference is a token naming the option. Storing the number would produce a document Tarinoi rejects on open.
3.6 Variables, lists and functions
Variable namespaces become variable collections — Tarinoi's Var.group.name is already two-level, so this is a direct match. Types and initial values come across; Integer widens to number.
Long variable names are truncated. A Tarinoi identifier is capped at 30 characters and an articy name is not, so long names are shortened and colliding truncations take a numeric suffix. The original articy name is written into the variable's description, so a renamed variable can always be matched back to the one your game knows. The renames are reported as a single finding with a count — see §6.3.
Declared script methods become Tarinoi function declarations. articy's JSON export declares only a name and a return type — no parameter list — so argument lists are reconstructed from the call sites in your project.
articy's built-in script functions have no Tarinoi equivalent and need your attention:
| articy built-in | What happens |
|---|---|
unseen, getSeenCounter(x) > 0 | Mapped where it can be — Tarinoi has shown_once on cards, and Fn.articy.HasSeen( <card> ) for the general case |
fallback() | A function stub is declared; you implement it |
getObj(), getProp() | A function stub is declared; you implement it |
Each of these is reported.
3.7 Locations, documents and everything else
articy's Locations sub-editor is a second authoring surface — a vector scene graph of zones, spots, paths and links over a map image. Tarinoi has no equivalent and deliberately does not intend to have one.
Locations are not dropped, because articy authors put real game logic in them: a zone routinely carries its click condition, its on-click instruction, the item the player must be holding and the flow node to run next. Instead, every object of a class Tarinoi does not map — Location, Zone, Spot, Path, Link, LocationImage, LocationText, Document, TextObject, and anything articy adds in future — becomes an entity, under a generated articy_<Type> template, in an entity collection named for its class — or, where one class spans several articy types, one collection per type: Zones (Zone) and Zones (Conditional zone).
Every articy property is carried, including the structural ones: a zone's vertex polygon, its transform, its clip rect and its anchors arrive as JSON text on the entity.
These entities are inert in Tarinoi
Nothing in Tarinoi renders a map, evaluates a zone condition or follows a location link. The data is in your project, your commits and your git remote, and your engine can read it through the public API or a Git remote like any other entity — but Tarinoi will never do anything with it, and its conditions will never fire. If your project's logic lives in the Locations editor, that logic is yours to reimplement.
3.8 Assets and media
Only two articy asset uses have a Tarinoi home: entity preview images become avatars, and container preview images become media cards. Everything else — voice-over takes, sound effects, unreferenced library images, location artwork — is not imported, and is reported grouped by kind rather than file by file.
Audio is the significant omission. Tarinoi has no voice-over model yet, and inventing a home for VO files now would mean migrating it again later. Keep your articy export; the audio is still in it.
Broken asset references are expected, not an error. An articy project can declare asset-typed properties on thousands of objects while exporting no assets at all. Those references import as unset and are counted in the report.
3.9 Text markup
articy text can carry formatting and inline markup. Tarinoi card text is plain: markup is stripped and reported. In practice this is rare enough to be a footnote rather than a migration risk.
4. Loss register
Everything that is not a clean one-to-one mapping, in one table.
| Item | Class | What it means for you |
|---|---|---|
| Flow topology, positions, sizes, colours | lossless | Nothing to do |
| Line text and speaker attribution | lossless | Nothing to do |
| Variable namespaces, types and defaults | lossless | Nothing to do |
| Enum property types → lists | lossless | Nothing to do |
| Input-pin condition placement | lossless | Nothing to do |
| Condition and instruction expressions | rewritten | Mechanical and reversible; your engine implements the functions they now call |
Condition nodes → input-pin conditions | restructured | Node count changes where a gate card was needed; behaviour does not |
| Feature grouping → flat properties | restructured | Property names gain a Feature_ prefix; nothing is lost |
| Jumps and connections target a card, not a pin | restructured | Only differs on multi-input-pin nodes; rare |
| Sub-flows are linked, not entered | restructured | Playback does not descend — see §6.4 |
| Long identifiers truncated | renamed | Original name kept in the description; reconcile with your engine's bindings |
MenuText, StageDirections | demoted | Now plain properties, outside playback and word counts |
| Locations, zones, paths, links, documents | inert | Imported as entities; their embedded logic does nothing in Tarinoi |
| Connection labels and per-connection colour | dropped | Re-author if you relied on them |
| Non-selected languages | dropped | Re-import per language, or wait for localisation support |
| Audio and unreferenced assets | dropped | Keep the articy export |
| Broken asset references | dropped | Imported as unset; counted in the report |
| Inline text markup | dropped | Stripped; reported |
articy built-ins (getObj, getProp, fallback) | stubbed | Function declarations exist; implementations are yours |
Nothing in this table blocks an import. The two rows that most often mean real work are Locations and sub-flows are linked, not entered.
5. Working the import report
Every import writes a report of what it changed, reinterpreted, or could not bring across. You get it three ways, and they are the same findings each time.
In the dialog, grouped by severity, as the import finishes. This copy is transient — closing the dialog loses it. Use it to decide whether the import went well, not to work from.
As a board in the project, named articy import report, placed first in the project tree so it is what opens the first time you open the project. This is the copy to work from. Each finding is an annotation card, laid out in a column per severity:
| Colour | Severity | Meaning |
|---|---|---|
| Deep orange | Not imported | Something in your articy project is not in your Tarinoi project |
| Amber | Imported, but changed | It came across, but not as it was |
| Light blue | Worth knowing | A decision was made that you might want to revisit |
Findings carry a category — flow, entities, templates, variables, functions, lists, script, assets, structure — as the card's title, and the finding itself as the body.
A finding about a specific card links to it. Those cards carry a card link above the text, which previews the card the finding concerns and can be followed to it. Focus the card and follow the link from the drawer — an annotation card has no clickable hotspot on the board itself. Findings about a template, a variable, or a whole class of object carry no link, because a link to one arbitrary card would be worse than none; where the finding came from an entity or a location rather than a card, the card link is empty and the document id is shown instead.
These are ordinary cards. Read one, act on it, delete it. Delete the board when it is empty. An import with no findings creates no board.
As import-report.txt at the root of the project's git branch, committed alongside the documents. This is the copy for reviewing a commit, diffing two imports of the same articy project, or grepping. Each finding there carries the same document id its board card shows, which is what ties the three copies together.
6. Finishing the import
An imported project opens and works. Getting it to the point where it plays well and your engine can read it takes a pass through the following. Work the report board first — it names the specific cards, templates and variables involved.
6.1 Decide what each card shows on its face
Imported cards deliberately show at most one property. articy's editor shows a node's whole template inline, and its boards are read at a zoom where that works. Tarinoi's boards are a graph, and a card carrying seven fields is a wall. So an imported card gets the one field a reader needs to recognise it, and everything else is one click away in the right-hand drawer.
The choice made for you:
| Card | Face |
|---|---|
| Line | The line |
| Annotation | The note |
| Jump | The target — the card link renders the destination's name |
| Blank with a card link | The link first, then one display field below it |
| Media | The image |
| Anything else | The template's first multi-language string property, if it has one — articy's own signal for "this is meant to be read" — otherwise nothing |
Card titles come from articy's display name. Line cards are the exception: their title is the speaker, which is what a Tarinoi line card always shows.
This is the first thing to adjust. Open a template, and drag the properties you want on the face into its display slot. It takes a few seconds per template and it is the single change that most affects how an imported project reads.
6.2 Check the player character
Tarinoi guessed. The report says which rule it used. Open the entity it picked and confirm — the player-character flag drives line rendering and playback, so getting it wrong is visible immediately and confusing for a while.
6.3 Reconcile renamed variables
If the report says variables were renamed, each renamed variable's description holds its original articy name. Your engine's bindings refer to the articy name; Tarinoi now refers to the truncated one. Either regenerate your bindings from Tarinoi (see §7) or rename the variables to something short you choose yourself, which is usually better than living with MetTheFerrymanAtTheRiverCr_2.
Rename them in Tarinoi rather than in the imported documents: Tarinoi rewrites every reference to a renamed variable, and a hand-edited document leaves those references dangling.
6.4 Flow that needs rebuilding
Two patterns do not survive:
Inline sub-flow descent. Where articy's player would descend into a container, run its contents and come back out, Tarinoi follows a link and the sub-flow ends where it ends. If your dialogue relies on this, wire the sub-flow's exit back to the container card's successor explicitly, or flatten the container.
Logic in the Locations editor. Zone conditions, on-click instructions and location links imported as entity data and do nothing. Anything that has to run needs a home in the flow — usually a card carrying the same function calls, placed where the interaction happens.
6.5 Implement the function stubs
Everything articy evaluated at runtime is now a function declaration in your Tarinoi project, and a declaration is a contract, not an implementation. CheckFlag, SetFlag, the counter comparators, and any stubs for articy built-ins all need implementing on your engine, which is where they belonged all along — Tarinoi deliberately does not ship a function library or know what your variables mean.
Both official plugins generate typed stubs for these from your project, so a missing implementation is a compile error rather than a runtime surprise.
6.6 Clean up
Once the report board is empty, delete it. It is an ordinary board; nothing depends on it.
7. Connecting your engine
An imported project is an ordinary Tarinoi project, so everything in the engine-integration documentation applies to it unchanged:
- Game Engine Plugins — start here, including how to connect a project
- Godot plugin and Unity plugin — the two official integrations, both MIT licensed
- Writing your own integration — the engine-agnostic data contract, traversal rules and expression grammar
- Document schemas — annotated JSON Schemas for every document type, and how templates relate to the documents that use them
- Public API and Git remotes — the two ways to get the data out
Three things specific to an imported project are worth knowing before you point an integration at it:
Generate your bindings after you have finished §6, not before. Identifiers change during the finishing pass — renamed variables most of all — and bindings generated from a half-finished import go stale immediately.
Rescued location and document entities are entities like any other, and will appear in generated entity constants. They carry their articy properties as ordinary data, including the structural ones as JSON strings. If your engine needs a zone polygon, it is there; you parse it.
Imported conditions call functions your game implements. The import does not decide what CheckFlag does — it decides that this condition is a CheckFlag call against that variable. The semantics stay where they were in articy: in your runtime.