Merge pull request #3 from LinpgFoundation/dev

[REVISION] vns-python 2.0

README.md

@@ -12,7 +12,11 @@ Unlike Ren'py, writing visual novel script is more like writing a story instead
 
 # How it started:
 
-The development of the VNS can be traced back to when Linpg was just developed. At that time, the team was searching for a way to store the dialogue. Ultimately, the team decided to use a dictionary (HashMap for Java forks) to store the data, which can be easily saved in the form of either JSON or YAML, while maintaining the readability. As a result, we end up with the following form today, which is almost identical to what we had in the very beginning, with only a few minor differences:
+The development of the VNS can be traced all the way back to the initial stages of Linpg's development. During this period, the team faced the challenge of finding an efficient method to store the dialogue. Each conversation required the storage of multiple variables, including the narrator, the actual dialogue content, associated character images, ambient background music, and various other components:
+
+![example](doc\readme_conv_ex.png)
+
+Ultimately, the team opted for a design inspired by doubly linked list, but implemented using dictionary (HashMap for Java forks). This approach not only facilitated easier access to the data but also  streamlined the saving process, enabling compatibility with formats like JSON or YAML. This method preserved readability while efficiently  managing the dialogue. Today, the current system closely resembles our initial design, with only a few subtle refinements:
 
 ```yaml
 compiledAt: ...
@@ -51,11 +55,13 @@ id: 1
 language: English
 ```
 
-Although the overall data is easy to read, it is somewhat inconvenient to write. We came up with a dedicated dialogue editor to resolve the issue, but it's still a bit of a hassle. That is the reason why we begin to inquire about the possibility of simplifying the process. Would it be possible to make it feel like we're writing the dialogue in a Microsoft Word document? Thus, VNS is born.
+Although the overall data is easy to read, it is somewhat inconvenient to write. We came up with a dedicated dialogue editor to resolve the issue, but it's still a bit of a hassle. That is the reason why we begin to inquire about the possibility of simplifying the process.
+
+Would it be possible to make it feel like we're writing the dialogue in a Microsoft Word document? Thus, VNS is born.
 
 # Tutorials:
 
-VNS are written in a plain text file with the `. vns` extension. The script file contains a series of tags, which are used to specify the different elements of the visual novel, such as the characters, backgrounds, dialogue, music, and so on.
+VNS are written in a plain text file with the `.vns` extension. The script file contains a series of tags, which are used to specify the different elements of the visual novel, such as the characters, backgrounds, dialogue, music, and so on.
 
 ## Tags with value
 
@@ -65,9 +71,9 @@ The `[tag]` represents the kind of value you are trying to represent, and the va
 
 ### ID:
 
-`[id]number`, ex: `[id]1`
+`[id]str`, ex: `[id]1`
 
-Specifies the ID of the current dialogue file. Every script file must have an ID.
+Specifies a (unique) ID for the current dialogue file. Every script file must have an ID.
 
 ### Language:
 
@@ -93,13 +99,13 @@ Specifies the background image for the current and following dialogues.
 
 Specifies the background music for the current and following dialogues.
 
-### Display characters
+### Display character(s)
 
 `[display]*str`, ex: `[display]character1.png character2.png`
 
 Displays the character(s) for the current and following dialogues.
 
-### Hide characters
+### Hide character(s)
 
 `[hide]*str`, ex: `[hide]character1.png character2.png` or `[hide]*` for hiding all.
 
@@ -111,31 +117,31 @@ Hides the character(s) for the current and following dialogues.
 
 Enters a new scene and displays the specified background image.
 
-### Label
+### Option(s)
 
-`[label]str`, ex: `[label]jump_point1`
+`[option]message->label`, ex: `[scene]Can you hear me?->yes_reply`
 
-Creates a label for the branch command.
+Adding option(s) to current dialogues, and branch to the specified label according to the option chosen by the player. 
 
-### Entry
+### Label
 
-`[entry]str`, ex: `[label]ifPickUpItem`
+`[label]str`, ex: `[label]jump_point1`
 
-Utilizes the value as the key for the subsequent conversation.
+Creates a label for the branch command. The value will be used as the key for the subsequent conversation.
 
 ## Tags without value
 
 ### End
 
 `[end]`
 
-Marks the end of the dialogue. Although the compiler will stop compiling immediately after reaching the end, it is still recommended that you add this tag to the end of your script file.
+Marks the end of the script.
 
 ### **Block**
 
 `[block]`
 
-The player can't go back to the previous dialogue.
+The player can't go back to the previous conversation.
 
 ### Comments:
 
@@ -147,11 +153,11 @@ Commenting the script to make it easier to understand.
 
 `// this is a note`
 
-Notes are very similar to comments. But usually, it's used to make a note for a specific conversation and is saved in the file that was made.
+Notes are very similar to comments. It's used to make a note for a specific conversation and is saved to the file that is compiled.
 
-## Dialogues:
+## Dialogue:
 
-Dialogues are written in the form of this:
+Conversations are written in the form of this:
 
 ```vns
 Character name:
@@ -181,8 +187,6 @@ Mabel:
 
 Dipper:
 - Hi Mabel! I'm doing well, thanks for asking.
-
-[end]
 ```
 
 This script would display the background image `bg1.png` and the character images `character1.png` and `character2.png`. Mabel would then say "Hello my name is Mabel!" and "How are you doing today!". Next, `character1.png` would be hidden and Dipper would say "Hi Mabel! I'm doing well, thanks for asking." Finally, the script would end.

examples/chapter1_dialogs_exp.json

@@ -1,5 +1,9 @@
 {
-    "compiledAt": 1695246451,
+    "compiler": {
+        "compiledAt": 1699907243,
+        "reversion": 0,
+        "version": 2
+    },
     "dialogs": {
         "dialog_example": {
             "head": {
@@ -19,6 +23,20 @@
                 },
                 "previous": null
             },
+            "jumping_point1": {
+                "background_image": "bg2.png",
+                "background_music": "bgm2.ogg",
+                "character_images": [
+                    "test_character1.png&silent",
+                    "test_character2.png&silent"
+                ],
+                "contents": [
+                    "Welcome to jump point 1"
+                ],
+                "narrator": "Test Character 3",
+                "next": null,
+                "previous": "~04"
+            },
             "~01": {
                 "background_image": "bg1.png",
                 "background_music": "bgm1.ogg",
@@ -27,13 +45,24 @@
                     "I hope it works."
                 ],
                 "narrator": "",
+                "next": null,
+                "previous": "head"
+            },
+            "~02": {
+                "background_image": null,
+                "background_music": null,
+                "character_images": [],
+                "contents": [
+                    "you cannot go back"
+                ],
+                "narrator": "",
                 "next": {
-                    "target": "~02",
+                    "target": "~03",
                     "type": "scene"
                 },
-                "previous": "head"
+                "previous": null
             },
-            "~02": {
+            "~03": {
                 "background_image": "bg2.png",
                 "background_music": "bgm2.ogg",
                 "character_images": [
@@ -48,12 +77,12 @@
                 ],
                 "narrator": "Test Character 1",
                 "next": {
-                    "target": "~03",
+                    "target": "~04",
                     "type": "default"
                 },
                 "previous": null
             },
-            "~03": {
+            "~04": {
                 "background_image": "bg2.png",
                 "background_music": "bgm2.ogg",
                 "character_images": [
@@ -64,8 +93,20 @@
                     "Hello I am test character 2."
                 ],
                 "narrator": "Test Character 2",
-                "next": null,
-                "previous": "~02"
+                "next": {
+                    "target": [
+                        {
+                            "id": "jumping_point1",
+                            "text": "click here to go to jump point 1"
+                        },
+                        {
+                            "id": null,
+                            "text": "click here to go to the end"
+                        }
+                    ],
+                    "type": "options"
+                },
+                "previous": "~03"
             }
         }
     },

examples/chapter_example.vns

@@ -12,6 +12,10 @@ null:
 null:
 - I hope it works.
 
+[block]
+null:
+- you cannot go back
+
 // section 2
 [scene]bg2.png
 [bgm]bgm2.ogg
@@ -20,5 +24,11 @@ Test Character 1:
 - Hello I am test character 1.
 Test Character 2:
 - Hello I am test character 2.
+[option]click here to go to jump point 1 -> jumping_point1
+[option]click here to go to the end -> null
+
+[label]jumping_point1
+Test Character 3:
+- Welcome to jump point 1
 
 [end]

vns-python/builder.py

@@ -1,4 +1,5 @@
 from linpgtoolbox.builder import Builder
+from os import path as OS_PATH
 
 # 需要额外包括的文件
 additional_files: tuple[str, ...] = (r"../README.md", r"../LICENSE")
@@ -25,8 +26,13 @@
 """
 action: str = input("Do you want to package and upload the latest build (Y/n):")
 if action == "Y":
+    Builder.copy(additional_files, OS_PATH.dirname(__file__))
     Builder.build()
     Builder.upload()
+    for additional_file in additional_files:
+        Builder.remove(
+            OS_PATH.join(OS_PATH.dirname(__file__), OS_PATH.basename(additional_file))
+        )
 elif action != "N":
     Builder.remove("src")
 """

vns-python/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyvns"
-version = "1.2"
+version = "2.0"
 authors = [
     {name = "Linpg Foundation", email = "[email protected]"},
 ]