Initial commit. Basic working version.

Author: weaversam8

.gitignore

@@ -0,0 +1,4 @@
+# examples/*.yarnc
+# examples/*.csv
+**/__pycache__
+.python-version

README.md

@@ -0,0 +1,90 @@
+# YarnRunner-Python
+
+An **unofficial** Python interpreter for compiled [Yarn Spinner](https://yarnspinner.dev/) programs. _Documentation incomplete._
+
+#### Using the library
+
+Here's an example illustrating how to use the library:
+
+```py
+from yarnrunner_python import YarnRunner
+
+# Open the compiled story and strings CSV.
+story_f = open('story.yarnc', 'rb')
+strings_f = open('story.csv', 'r')
+
+# Create the runner
+runner = YarnRunner(story_f, strings_f, autostart=False)
+
+# Register any command handlers
+# (see https://yarnspinner.dev/docs/writing/nodes-and-content/#commands)
+def custom_command(arg1, arg2):
+    pass
+
+runner.add_command_handler("customCommand", custom_command)
+
+# Start the runner and run until you hit a choice point
+runner.resume()
+
+# Access the lines printed from the story
+print('\n'.join(runner.get_lines()))
+
+# Access the choices
+for choice in runner.get_choices():
+    print(f"[{choice.index}] ${choice.text}")
+
+# Make a choice and run until the next choice point or the end
+runner.choose(0)
+
+# Access the new lines printed from the last run
+print('\n'.join(runner.get_lines()))
+
+# Are we done?
+if runner.finished:
+    print("Woohoo! Our story is over!")
+```
+
+A few gotchas to look out for:
+
+- Calling `runner.get_lines()` or `runner.get_line()` is a destructive operation, it fetches the current lines (or line) from the line buffer and then pops them from the buffer. Therefore, calling `runner.get_lines()` twice in a row without making a choice will give you different results. **Feedback on this approach is welcome!**
+- Make sure to open the compiled story file as a binary file (see the above example, use `open(filename, 'rb')`) in order for it to be properly parsed by the compiled protobuf library.
+- Unless you pass `autostart=False` to the runner when creating it, it will automatically start and run to the next choice point.
+
+Only a subset of Yarn Spinner opcodes are currently implemented. This will certainly change over time. The current status is:
+
+| OpCode           | Status                                               |
+| ---------------- | ---------------------------------------------------- |
+| `JUMP_TO`        | 🚫  Not Implemented                        |
+| `JUMP`           | 🚫  Not Implemented                        |
+| `RUN_LINE`       | ✅  Implemented in `runner.__run_line`     |
+| `RUN_COMMAND`    | ✅  Implemented in `runner.__run_command`  |
+| `ADD_OPTION`     | ✅  Implemented in `runner.__add_option`   |
+| `SHOW_OPTIONS`   | ✅  Implemented in `runner.__show_options` |
+| `PUSH_STRING`    | 🚫  Not Implemented                        |
+| `PUSH_FLOAT`     | 🚫  Not Implemented                        |
+| `PUSH_BOOL`      | 🚫  Not Implemented                        |
+| `PUSH_NULL`      | 🚫  Not Implemented                        |
+| `JUMP_IF_FALSE`  | 🚫  Not Implemented                        |
+| `POP`            | 🚫  Not Implemented                        |
+| `CALL_FUNC`      | 🚫  Not Implemented                        |
+| `PUSH_VARIABLE`  | 🚫  Not Implemented                        |
+| `STORE_VARIABLE` | 🚫  Not Implemented                        |
+| `STOP`           | ✅  Implemented in `runner.stop`           |
+| `RUN_NODE`       | ✅  Implemented in `runner.__run_node`     |
+
+## Development
+
+This project uses Python 3 and has a basic test suite.
+
+1. `pip install -r requirements.txt`
+2. `py.test`
+
+## Updating the examples
+
+The source code of the examples are located inside `*.yarn` files. `*.csv` and `*.yarnc` files are generated via the Yarn Spinner compiler. To compile these files, follow the below steps:
+
+1. Install the [Yarn Spinner Console](https://github.com/YarnSpinnerTool/YarnSpinner-Console) program `ysc`. Basic binaries are available on [their releases page](https://github.com/YarnSpinnerTool/YarnSpinner-Console/releases).
+2. From the `examples/` directory, run `ysc compile [filename].yarn`. For example, to compile the basic example used in `tests/test_basic.py`, use `ysc compile basic.yarn`.
+   - This will output `*.csv` and `*.yarnc` files in the current directory, overwriting any files already present with the same name.
+
+Currently `*.csv` and `*.yarnc` files are committed to version control to make it easier to run our test suite. They will likely be gitignored later once we have a better build process for these files.

examples/basic.csv

@@ -0,0 +1,5 @@
+id,text,file,node,lineNumber
+basic-Start-0,This is the first node.,basic,Start,3
+basic-Start-1,Choice 1,basic,Start,5
+basic-Start-2,Choice 2,basic,Start,6
+basic-choice_1-3,"Here is the node visited as a **result** of the __first__ ""choice"", with a comma.",basic,choice_1,11

examples/basic.yarn

@@ -0,0 +1,15 @@
+title: Start
+---
+This is the first node.
+
+[[Choice 1|choice_1]]
+[[Choice 2|choice_2]]
+===
+title: choice_1
+---
+
+Here is the node visited as a **result** of the __first__ "choice", with a comma.
+
+<<runACommand arg1 2 event:/event/event_name >>
+
+===

examples/basic.yarnc

@@ -0,0 +1,2 @@
+protobuf==3.19.1
+pytest==6.2.5

requirements.txt

@@ -0,0 +1,9 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath(
+    os.path.join(os.path.dirname(__file__), '..')))
+
+# the "nopep8" is to ensure this is below "sys.path", autopep8 will autoformat it above otherwise
+from yarnrunner_python import YarnRunner  # nopep8
+
+# for the structure of this file, see https://docs.python-guide.org/writing/structure/#test-suite

tests/__init__.py

@@ -0,0 +1,47 @@
+import os
+from .context import YarnRunner
+
+compiled_yarn_f = open(os.path.join(os.path.dirname(
+    __file__), '../examples/basic.yarnc'), 'rb')
+names_csv_f = open(os.path.join(os.path.dirname(
+    __file__), '../examples/basic.csv'), 'r')
+
+runner = YarnRunner(compiled_yarn_f, names_csv_f)
+
+
+def test_start_node_text():
+    assert "This is the first node." == runner.get_line()
+    assert not runner.has_line()
+    assert not runner.finished
+
+
+def test_start_node_choices():
+    choices = runner.get_choices()
+
+    assert len(choices) == 2
+    assert choices[0]["choice"] == "choice_1"
+    assert choices[1]["choice"] == "choice_2"
+    assert choices[0]["text"] == "Choice 1"
+    assert choices[1]["text"] == "Choice 2"
+
+
+side_effect = None
+
+
+def run_a_command(arg1, arg2, arg3):
+    global side_effect
+    side_effect = arg3
+
+
+runner.add_command_handler("runACommand", run_a_command)
+
+
+def test_start_node_choose():
+    runner.choose(0)
+
+    assert "Here is the node visited as a **result** of the __first__ \"choice\", with a comma." == runner.get_line()
+    assert not runner.has_line()
+    assert runner.finished
+
+    # ensure the command has run
+    assert side_effect == "event:/event/event_name"

tests/context.py

@@ -0,0 +1,143 @@
+syntax = "proto3";
+package Yarn;
+
+// Copyright (c) 2015-2017 Secret Lab Pty. Ltd. and Yarn Spinner contributors.
+// This file is copied from YarnSpinner/YarnSpinner@fb2d6db, which is licensed MIT.
+// It should be updated if Yarn makes any changes to their protocol for compiled code.
+
+// A complete Yarn program.
+message Program {
+
+	// The name of the program.
+	string name = 1;
+	
+	// The collection of nodes in this program.
+    map<string, Node> nodes = 2;   	
+}
+
+// A collection of instructions
+message Node {
+	// The name of this node.
+	string name = 1;
+	
+	// The list of instructions in this node.
+    repeated Instruction instructions = 2;
+
+    // A jump table, mapping the names of labels to positions in the
+    // instructions list.
+	map<string, int32> labels = 3;
+	
+	// The tags associated with this node.
+	repeated string tags = 4;
+
+	// the entry in the program's string table that contains the original
+	// text of this node; null if this is not available    
+	string sourceTextStringID = 5;
+}
+
+// A single Yarn instruction.
+message Instruction {
+
+	// The operation that this instruction will perform.
+	OpCode opcode = 1;
+
+	// The list of operands, if any, that this instruction uses.
+    repeated Operand operands = 2;
+
+	// The type of instruction that this is.
+    enum OpCode {
+		
+		// Jumps to a named position in the node.
+		// opA = string: label name
+		JUMP_TO = 0; 
+		
+		// Peeks a string from stack, and jumps to that named position in
+		// the node. 
+		// No operands.
+		JUMP = 1; 
+		
+		// Delivers a string ID to the client.
+		// opA = string: string ID
+		RUN_LINE = 2; 
+		
+		// Delivers a command to the client.
+		// opA = string: command text
+		RUN_COMMAND = 3; 
+		
+		// Adds an entry to the option list (see ShowOptions).
+		// opA = string: string ID for option to add
+		ADD_OPTION = 4; 
+		
+		// Presents the current list of options to the client, then clears
+		// the list. The most recently selected option will be on the top
+		// of the stack when execution resumes.
+		// No operands.
+		SHOW_OPTIONS = 5; 
+		
+		// Pushes a string onto the stack.
+		// opA = string: the string to push to the stack.
+		PUSH_STRING = 6; 
+		
+		// Pushes a floating point number onto the stack.
+		// opA = float: number to push to stack
+		PUSH_FLOAT = 7; 
+		
+		// Pushes a boolean onto the stack.
+		// opA = bool: the bool to push to stack
+		PUSH_BOOL = 8; 
+		
+		// Pushes a null value onto the stack.
+		// No operands.
+		PUSH_NULL = 9; 
+		
+		// Jumps to the named position in the the node, if the top of the
+		// stack is not null, zero or false.
+		// opA = string: label name 
+		JUMP_IF_FALSE = 10; 
+		
+		// Discards top of stack.
+		// No operands.
+		POP = 11; 
+		
+		// Calls a function in the client. Pops as many arguments as the
+		// client indicates the function receives, and the result (if any)
+		// is pushed to the stack.
+		
+		// opA = string: name of the function
+		CALL_FUNC = 12; 
+		
+		// Pushes the contents of a variable onto the stack.
+		// opA = name of variable 
+		PUSH_VARIABLE = 13; 
+		
+		// Stores the contents of the top of the stack in the named
+		// variable. 
+		// opA = name of variable
+		STORE_VARIABLE = 14; 
+		
+		// Stops execution of the program.
+		// No operands.
+		STOP = 15; 
+		
+		// Run the node whose name is at the top of the stack.
+		// No operands.
+		RUN_NODE = 16; 
+    }
+}
+
+// A value used by an Instruction.
+message Operand {
+
+	// The type of operand this is.
+    oneof value {
+		
+		// A string.
+		string string_value = 1;
+		
+		// A boolean (true or false).
+		bool bool_value = 2;
+
+		// A floating point number.
+		float float_value = 3;
+    }
+}