add README

Author: Icemic

README.md

@@ -0,0 +1,157 @@
+# Storyscript
+
+[中文版请点击此处 (View Chinese Edition)]()
+
+## Introduction and Design Ideas
+
+Storygscript is a set of scripting systems for expressing AVG stories and is one of the official modules of AVG.js. Similar to the scripting system of other AVG engines, it is executed in the order of text; grammatically, it is quite similar to BKEngine's scripting system, but simpler.
+
+The previous AVG script, including the entire game of all the program logic, but relatively Lua, Javasciprt and other mature programming language, the markup language syntax is very simple, on this basis to achieve the program logic, whether programmers or ordinary enthusiasts Are a troubled.
+
+AVG.js AVG script has been stripped off the game UI, performance effects and other strong logic, and the rest is only a simple instructional code, which is the origin of the name Storyscript.
+
+Storyscript aims to reduce the difficulty of learning, so that non-programmers can fully grasp their use, so that designers and other personnel to complete the production of game content and reduce unnecessary communication links.
+
+For more information about AVG.js and Storyscript, please visit <https://avgjs.org>
+
+## Installation and Usage
+
+Storyscript has been built into the AVG.js project as the initial module. If you want to use it in AVG.js, please refer to the AVG.js tutorial.
+
+If used in other projects, as follows:
+
+**Installation**
+
+```shell
+npm install avg-storyscript
+```
+
+**Usage**
+
+```javasciprt
+import Story from 'avg-storyscript';
+const story = new StoryScript();
+story.load(scriptString);
+for (const line of story) {
+  // do something
+}
+```
+
+Refer to the test.js file for details.
+
+## Syntax
+
+StoryScript consists of **Content Script** and **Logical Script**.
+
+Content script: changes in the game plot, such as print dialogue text, display characters, switch the background picture, play sound, etc.
+
+Logic Script: Controls the direction of the game plot or provides convenient programming logic such as variable assignment, conditional branching, loops, etc.
+
+### Content Script
+
+**Basic**
+
+```shell
+[command flag param="value"]
+```
+
+For example
+
+```shell
+[bgm autoplay loop file="abc.ogg" volume=100]
+```
+
+Will be parsed as
+
+```javasciprt
+{
+  command: 'bgm',
+  flags: ['autoplay', 'loop'],
+  params: {
+    file: "abc.ogg",
+    volume: 100
+  }
+}
+```
+
+### Logical Script
+
+#### Statement
+
+**LET**
+
+```
+#let foo = 123  // standard way
+#bar = 456      // omit let
+#let foobar     // can not assign value (value will be null), thus `let` can not be omitted
+```
+
+**If**
+
+```
+#if foo > bar
+// do something
+#elseif foo == bar
+// do something
+#else
+// do something
+#end
+```
+
+Among them, `elseif` and`else` are optional.
+
+**While**
+
+```
+#while i < 10
+// do something
+#end
+```
+
+Currently `break` and`continue` are not supported, but they are in TODO list :)
+
+**Foreach**
+
+```
+#foreach child in children
+// do something
+#end
+```
+
+`children` is an array, there are some special circumstances, please read on.
+
+#### Variables
+
+Support for simple variable assignment and modify operations, and to meet the needs of AVG, different variables in the archive have different treatment.
+
+**Global Archive Variables**
+
+Variables that begin with `$` will be treated as global archive variables, meaning that once assigned, they will be read in any case, either by reading a new archive or by using a previous archive. You can use it to control the unlock CG appreciation, or support _New Game+_.
+
+```
+#let $gameclear = true;
+```
+
+**Single archive variable**
+
+Variables that start with `%` are treated as single archive variables, meaning that they will only be valid in certain archives and will be overwritten when other archives are read. Usually used to control the route or favorability.
+
+```
+#let %girl_favor_num = 1;
+```
+
+**Common variables**
+
+In other cases, the variable name is a normal variable, in the archive, only the archive point where the "block" and the parent "block" common variables will be saved (see below). Common variables are used only for single-file use. Do not use them to save favorability.
+
+```
+#let x = 0;
+```
+
+**Scopes**
+
+Global archive variables and single archive variables are valid at any location, and are therefore considered global variables.
+
+(NOTE: The global archive variable is completely unrelated to the global variable, the former is about how it is saved in the archive, while the other is about where it can be access in the game script)
+
+For a normal variable, its scope is "block", such as an IF branch or the contents of the While statement, are a "block." The largest "block" is the "file", that is, even if you do not declare variables such as IF While, but outside of them, variables in the scope of the work is limited to the current script file.

README_zh.md

@@ -0,0 +1,157 @@
+# Storyscript
+
+## 简介及设计思想
+
+Storyscript 是一套用于表达 AVG 剧情的脚本系统，是 AVG.js 的官方模块之一。与其他 AVG 引擎的脚本系统类似，它也是依照文本顺序依次执行；语法上，与 BKEngine 的脚本系统颇为类似，但更为简单。
+
+以往的 AVG 脚本，包含了整个游戏全部的程序实现，但相对 Lua、Javasciprt 等成熟的程序语言，其类似标记语言的语法却十分简陋，在这个基础上实现程序逻辑无论对程序员还是普通的爱好者都是一份困扰。
+
+AVG.js 已经将游戏UI、演出效果等强逻辑内容从 AVG 脚本中剥离，剩下的只有简单的指令性代码，这便是 Storyscript 之名的由来。
+
+Storyscript 致力于降低学习难度，让非程序员完全能够掌握其使用方法，使策划、剧本、演出师等人员能够自行完成游戏内容的制作，减少不必要的沟通环节。
+
+有关 AVG.js 及 Storyscript 的详细信息请访问 <https://avgjs.org>
+
+## 安装与使用
+
+Storyscript 已作为初始模块内置于 AVG.js 工程中，若你想要在 AVG.js 中使用它，请参考 AVG.js 相关教程。
+
+下面只介绍在其他工程中的使用方法：
+
+**安装**
+
+```shell
+npm install avg-storyscript
+```
+
+**使用**
+
+```javasciprt
+import Story from 'avg-storyscript';
+const story = new StoryScript();
+story.load(scriptString);
+for (const line of story) {
+  // do something
+}
+```
+
+详细请参考 test.js 文件
+
+## 语法简介
+
+Storyscript 脚本系统分为**内容脚本**和**逻辑脚本**。
+
+内容脚本：表示游戏剧情的变化，如打印对话、显示立绘、切换背景图片、播放声音等
+
+逻辑脚本：控制游戏剧情的走向或提供一些方便的程序功能，如变量赋值、条件分支、循环等
+
+### 内容脚本
+
+**基本语法**
+
+```shell
+[command flag param="value"]
+```
+
+command: 指令名<br>
+flag: 标记<br>
+param: 参数
+
+例如
+
+```shell
+[bgm autoplay loop file="abc.ogg" volume=100]
+```
+
+将被解析为
+
+```javasciprt
+{
+  command: 'bgm',
+  flags: ['autoplay', 'loop'],
+  params: {
+    file: "abc.ogg",
+    volume: 100
+  }
+}
+```
+
+### 逻辑脚本
+
+#### 语句
+
+**LET**
+
+```
+#let foo = 123  // 标准方式
+#bar = 456      // 可省略 let
+#let foobar     // 可不赋值（值为null），此时 let 不可省略
+```
+
+**If**
+
+```
+#if foo > bar
+// do something
+#elseif foo == bar
+// do something
+#else
+// do something
+#end
+```
+
+其中，`elseif` 和 `else` 都是可选的。
+
+**While**
+
+```
+#while i < 10
+// do something
+#end
+```
+
+暂不支持 `break` 和 `continue`，它们还在 TODO 列表中 : )
+
+**Foreach**
+
+```
+#foreach child in children
+// do something
+#end
+```
+
+`children` 是一个数组，这里有一些特殊的情况，请往下阅读。
+
+#### 变量
+
+支持简单的变量赋值和修改操作，同时为适应 AVG 游戏的需求，不同的变量在存档时有不同的处理。
+
+**全局存档变量**
+
+以 `$` 开头的变量将被视为全局存档变量，意思是说，它一旦被赋值将在任何情况下都能被读取，无论是读取了新的档案还是使用以前的档案。你可以用它来控制CG鉴赏的解锁，或是标明周目数。
+
+```
+#let $gameclear = true;
+```
+
+**单存档变量**
+
+以 `%` 开头的变量将被视为单存档变量，意思是说，它将只在某些特定的存档中有效，读取其他档案后将被覆盖。通常用来控制路线或好感度。
+
+```
+#let %girl_favor_num = 1;
+```
+
+**普通变量**
+
+其他情况下的变量名都是普通变量，在存档中，只有存档点所在的「块」及父「块」中的普通变量将被保存（见下）。普通变量仅用于单文件内使用，请勿用于保存好感度等。
+
+```
+#let x = 0;
+```
+
+**作用域**
+
+全局存档变量和单存档变量在任何位置都有效，故可视为全局变量（注：全局存档变量和全局变量完全没有联系，前者是说其在存档中的保存方式，后者是说其在游戏脚本中何处可以读取）
+
+对于普通变量，它的作用域是「块」，如一个 IF 分支中的内容或 While 语句中的内容，均为一个「块」。最大的「块」是「文件」，也就是说，即使你不在 IF While 等语句块中声明变量，而是在它们的外面，变量起作用的范围也仅限于当前的脚本文件。