jujuadams/chatterbox

GameMaker 2022 LTS implementation of the Yarn narrative design language

You might know me from my commerical work or one of the talks I gave, but I spend my free time making libraries to help developers.

GML is something of a quirky language and has led me to evolve particular techniques to establish a personal "best practice". You can read some of my thoughts on the nuances of developing in GameMaker here.

 

The Jujuverse The most popular libraries, all in one place
	Scribble Deluxe Powerful, fully featured text renderer		Input Comprehensive cross-platform input Now maintained by offalynne
	Scribble Jr. Fast and lightweight text renderer		Vinyl Live updating modular audio system
	SNAP Struct and array export/import and utilities		Chatterbox Narrative scripting tool
	Dynamo Dynamic data loading		Snitch Logging and crash handling system
	iota Miniature fixed timestep library		Bulb 2D lighting and shadows
	Texan Texture group manager		DoLater call_later but with arguments
	Clean Shapes Antialiased primitive drawing		db Simple savedata database

 

Other stuff you might like too:

dotobj Comprehensive .obj importer	Cardboard Z-tilt / isometric 3D rendering
Elephant Advanced struct/array serialization	Coroutines Asynchronous functions for GameMaker
Shockwaves Shader-based ripple distortion	Kawase Blur Kawase dual filter blur
LUT Commonly used for colour grading	A Message from Amalthea Procedural audio toy
Quaternions Simple quaternion library	Matrices Matrix manipulation functions
Sphinx Simple encryption	HMAC-Secured Savedata Featured on the YoYoGames tech blog
Reddit / YouTube OAuth frameworks for social networks	Google Analytics Google's Measurement Protocol v4
gl_FragDepth How to enable gl_FragDepth in GLSL ES	BIG Integers Big integer handling
Extending JSON Experimental JSON-like data formats	PRNG PRNG functions
Ugg 3D primitives	Splat Vertex buffer-based sprite caching

chatterbox's Issues

Function to count characters+words+nodes across all source files

When sending off text/dialogue for localisation, it's often useful to have an idea of how many words are in the source files. This is used to inform budgeting and scheduling. A function should exist that spits out this information for the user.

Add function to return if a <<wait>> or singleton wait has been encountered

Check for old deprecated code in error message

e.g. use of chatterbox_add_action() instead of chatterbox_add_function()

Refactor expression evaluator

The current expression evaluator is weird and bad and it's inherited from the GMS2.2.5 version that didn't have structs. It needs replacing!

<<script>> and <<end script>> tags

Check if action execution is compliant with Yarn

The current action execution syntax <<function arg0 arg1>> might not be properly compliant with the current version of Yarn. This needs checking.

Add support for <<shuffleNextOptions>>

Yarn has a feature to randomise the order of options presented to the player:

<<shuffleNextOptions>>
-> One
-> Two
-> Three
-> Four

These options should NOT be shuffled:
-> One
-> Two
-> Three
-> Four

Chatterbox should support this as well.

Convert internal functions to methods

Rename "internal" variable access type to "yarn"

"internal" is confusing and vague!

Cannot detect variables

I'm always getting

Chatterbox: WARNING! Local variable "c" doesn't exist
Chatterbox: WARNING! Local variable "c" doesn't exist
Chatterbox: WARNING! Local variable "d" doesn't exist
Chatterbox: WARNING! Internal variable "variable" doesn't exist

When trying to use variables or running Test.json in the oBeginnerExample

<<declare>> should set default values at compiletime

Add fast-forward functionality

chatterbox_add_function() should be able to be called on boot

Implement //comments in Yarn files

Comments are supported in Yarn files but prefixing a line with //. Chatterbox should skip these lines when parsing source files.

GM silently crashes when using <<set>>

1. Create a variable dialogue = 0 in obj_testcase_option and load this yarn file:

title: Start
tags: 
position: 0,0
---
NPC: Talk talk
-> Talk
    <<if local.dialogue == 0>> 
        NPC: Dialogue 0
        <<set local.dialogue to 1>>
    <<elseif local.dialogue == 1>> 
        NPC: Dialogue 1
        <<set local.dialogue to 0>>
    <<endif>>
-> Exit
    NPC: Bye!
===

2. Press 1
3. Press Space

It crashes the game silently. It runs if you remove the <<set>>s.

Actions can't be used in shortcuts

Say you have:

Chara: Starting the dialogue...
-> Shortcut 1
    Chara: Hello world <<action>>
    Chara: This shortcut has two lines.
->
Chara: Hello again world <<action>>

(with correct indentation ofc)

What you'll get is:
Chara: Starting the dialogue...

1. Shortcut 1
   (press 1)
   Chara: Hello world <>
2. Shortcut 2
   (press 1)
   Chara: Hello again world <>

In other words, the menu doesn't generate properly, and any extra lines under the shortcut are skipped, instead going straight to the next shortcut.

Workaround: just use nodes. Annoying but stable.

Add function to clean up uses of \n literal

Add safety check against CHATTERBOX_DIRECTION_FUNCTION

chatterbox_goto should support going to a node in another loaded file

This is supported from the actual .yarn files, as described in the wiki, but there isn't a way to do it from code without creating another chatterbox.

Function to collect all internal Yarn variables starting with a particular header

shdwcat: so if in my yarn I'm going around setting $mae.opinion to 'favorable' and $mae.mood to 'sad' or whatever, I was wondering if from gms2 I could be like 'chatterbox, what are all the mae.* variables' ?

Add basic string parsing functions to set the speaker for a line of text

Character: Text
-->
{ character : "Character", text : "Text"]

Character, expression, more details: Text
-->
{ character : ["Character", "expression", "more details"], text : "Text"}

Add internal variable serialise/deserialise functions

if-statements blocks pause in a middle of option chains

I've tried to make an if-statement block option but it seems that it blocks the proceeding of the option chains. Only in-line if-statements work
Examples:
in-line if-statement
[[ What if I want to? |GoingToFight]] << if $testVariable is 0>>
block if-statement
<< if $testVariable is 0>> [[ What if I want to? |GoingToFight]] << endif>>
It would be great if chatterbox supports the two syntax!

Feature to check jump node names on compile

Reloading a source file shouldn't throw a loud error

A node will return visited as true even if this is the first time it is being visited

In the yarn language tutorial the visited function is shown to mark a node as visited only if it was already visited once before, not if this current visit is your first visit, this is useful as it allows simply using the visited script to create a simple loop going back to the chatterbox's Start node without creating any additional logics.

In the chatterbox implementation the visited function marks visited on the first visit, so it's impossible to return false on visited if asking about current node.

The fix is very simple but I'm very much a github noob so I don't know how to submit it, in the ChatterboxCreate script file inside the static jump function, the node is marked as visited at the end of the function after the current node has already been changed, moving mark visited to be before the new current node assignment (and wrapping it with an if(current_node) statement to make sure that current node actually exists which it wouldn't if this is the first jump) solves this and allows you to use the visited function the same way it is shown in the yarn tutorial.

And thank you for this awesome library (and for scribble) Juju, you are awesome :)

chatterbox_is_loaded() + chatterbox_unload()

For large games, we might not want to store 100% of our dialogue in memory all the time, especially when dealing with localisation. Having a couple functions to handle unloading of source files will allow developers to manage memory more effectively.

Add check for non-defined generic commands

Yarn $variables do not autodeclare when using <<set ... to ...>>

Chatterbox: Trying to set Yarn variable $PestleInCamp but it has not been declared
with Yarn
<<set $PestleInCamp to 1>>
Version: 2.2.2, 2022-01-09
IDE: latest beta

Clean up old/orphaned .yy files

Implement in-line evaluation

As per this test case: https://github.com/YarnSpinnerTool/YarnSpinner/blob/master/Tests/TestCases/InlineExpressions.yarn

Strange IF-Statement Weirdness

It looks like a lot of yarn things have spaces between them.

Add macro to convert \n literals to actual newlines

Code Error when using a function without passing arguments

Yarn code that works as intended:

<< set $timeOfDay to getTimeOfDay("") >>

Yarn code that causes error:

<< set $timeOfDay to getTimeOfDay() >>

Function being added and called:

function getTimeOfDay(){
	switch global.ToD
	{
		case timeOfDay.morning:		{ return "morning";		break; }
		case timeOfDay.afternoon:	{ return "afternoon";	break; }
		case timeOfDay.evening:		{ return "evening";		break; }
	}
}

Custom function added before the file is loaded. Error is thrown when using the "ChatterboxLoadFromFile" function to load the yarn file containing the code.

Error message:

___________________________________________
############################################################################################
ERROR in
action number 1
of Create Event
for object ArgyBargy_Manager:

Push :: Execution Error - Variable Index [0] out of range [0] - -7.<unknown variable>(100469,0)
 at gml_Script___ChatterboxCompileExpression (line 55) -                     var _is_function = (_last_byte == ord("(")); //Cheeky hack to find functions
############################################################################################
gml_Script___ChatterboxCompileExpression (line 55)
gml_Script___ChatterboxParseExpression (line 321) -     __ChatterboxCompileExpression(_tokens);
gml_Script___ChatterboxCompile (line 264) -                     _instruction.expression = __ChatterboxParseExpression(_remainder, false);
gml_Script___ChatterboxClassNode (line 34) -     __ChatterboxCompile(_substring_array, root_instruction);
gml_Script___ChatterboxClassSource (line 41)
gml_Script_ChatterboxLoadFromBuffer (line 33)
gml_Script_ChatterboxLoadFromFile (line 36) -         return ChatterboxLoadFromBuffer(_aliasName, _buffer);
gml_Script_initGlobals (line 186) -        ChatterboxLoadFromFile("test.yarn", "ArgyBargyTest");
gml_Object_ArgyBargy_Manager_Create_0 (line 6) - initGlobals();

Feature request: Reset visited() function

I want to let the player reset the game, but since I use visited() to mark what dialogue should play, various dialogue scenes don't play even after resetting. I can see a "variable map" where visited data is kept, but I'm kinda scared to mess with it on my own...

Update to YarnScript v2 (!)

Add setting to have chatterbox pause/wait before loading options

Currently in singleton mode if you have:

Sara: This is a first line.
Sara: This is a second line.
-> this is a shortcut
    [[JumpToNode]]

This gets translated via chatterbox (essentially) to:

Sara: This is a first line.
<<wait>>
Sara: This is a second line.
-> this is a shortcut
    [[JumpToNode]]

but an option to have it be:

Sara: This is a first line.
<<wait>>
Sara: This is a second line.
<<wait>>
-> this is a shortcut
    [[JumpToNode]]

would be really nice. Some styles of games don't display the options until after user input after the last piece of dialogue. This would just make chatterbox more flexible for people to use.

Add ChatterboxVariableDefault()

ChatterboxVariableGet() will return undefined if a variable hasn't been set by executing YarnScript. This is confusing and frustrating for new users. Instead, we can introduce a GML-side function that allows setting of a default value for any given variable.

Inline Expressions

Most notably, {$variables} in text.

Support #line:xxxxx tags

Yarn can tag lines by suffixing #line:xxxxxx, where xxxxxx is a unique string of characters. These are commonly used for localisation. I couldn't see a way to generate these tags in the Yarn Editor (more investigation needed) so we may need to create a function to mark up lines in addition to correctly parsing them.

Check for bugs in GML-side variable getter/setter

See https://discord.com/channels/724320164371497020/724320386816409690/872328905070092289

Feature request: Function to check if it's the first time visiting a node

This request is to be able to check if it's the first time visiting a Chatterbox node. Ideally, this is something that can also be reset (maybe with the future feature to reset visited()?). A potential name could be something like <<firstVisited>>

Chatterbox crashes in only if-statement nodes

Hi Juju! I've wanted to make a node to decide wich node go into. Unfortunately, GM crashes when I do that
Yarn:

<<if !visited("Intro")>>
    [[Intro]]
<<else>>
    [[WakingUp]]
<<endif>>

Error at launch loading the file with the node:

___________________________________________
############################################################################################
ERROR in
action number 1
of Create Event
for object oChatterbox:

Push :: Execution Error - Variable Index [1] out of range [1] - -15.argument0(91,1)
 at gml_Script___chatterbox_compile_expression (line 846) -                 _token.a = _source_array[_t+1];
############################################################################################
gml_Script___chatterbox_compile_expression (line 846)
gml_Script___chatterbox_parse_expression (line 731) -     __chatterbox_compile_expression(_tokens);
gml_Script___chatterbox_compile (line 273) -                         _instruction.condition = __chatterbox_parse_expression(_remainder, false);
gml_Script___chatterbox_class_node (line 33) -     __chatterbox_compile(_substring_list, root_instruction);
gml_Script___chatterbox_class_source (line 48)
gml_Script_chatterbox_load_from_buffer (line 33)
gml_Script_chatterbox_load_from_file (line 47) -     return chatterbox_load_from_buffer(_filename, _buffer);
gml_Script_Setting_Chatterbox (line 5) -        chatterbox_load_from_file("intro.yarn")
gml_Object_oChatterbox_Create_0 (line 14) - Setting_Chatterbox();

Hope you'll find the cause!

Replaces most (all?) of the string parsing with buffer solution for extra speeeeeeed

Do we want to support "format functions"?

Yarn has the ability to do many advanced, flexible things with dialogue, as shown by this test case: https://github.com/YarnSpinnerTool/YarnSpinner/blob/master/Tests/TestCases/FormatFunctions.yarn

This aids with localisation significantly but is an enormous amount of work.

chatterbox_load_from_buffer()

At the moment, Chatterbox presumes you're loading text from a plaintext file. However, sometimes we might want to encrypt source files or even distribute them outside the game's initial installation. Adding a way to load source files (both .yarn and .json formats) from a buffer will expand Chatterbox's functionality.

Add a function to check if a node with a given name exists

Something like:

if (ChatterboxNodeExists(my_chatterbox, "my_node_name"))
{
    //Success!
}

Implement official Yarn test cases

Yarn added some test cases since the last time I checked! These should be implemented so that development can continue safely.

https://github.com/YarnSpinnerTool/YarnSpinner/tree/master/Tests

Offer GML YarnScript composition functions

Rebuild <<command>> tag functionality to execute functions (for v2)