Adds initial docs.

HopsonCommunity · Dec 21, 2017 · a4661e5 · a4661e5
1 parent a270663
commit a4661e5
Show file tree

Hide file tree

Showing 4 changed files with 359 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,43 @@
-# GraphicsInterface
+# Text Community Game
 
-Graphics interface for creating terminal-looking applications in GUI windows.
+Single player, text-based RPG in wild west.
 
-[Example](docs/example.md)
+**Graphics Engine**
+
+## Trivia:
+
+* **Platform** - PC
+* **Language** - Python 3.5+
+* **Theme** - Wild West
+* **Visual Style** - Pixel Art
+* **Audio Style** - Chiptunes
+
+## Parts:
+
+### Story Engine
+
+* [Git Repository](https://github.com/HopsonCommunity/TextAdventure)
+* [Agile Board](https://trello.com/b/hNnX2awR/hopson-communitys-text-game)
+* [Issue Tracker](https://github.com/HopsonCommunity/TextAdventure/issues)
+
+### Graphics Engine
+
+* [Git Repository](https://github.com/HopsonCommunity/GraphicsInterface)
+* [Agile Board](https://trello.com/b/nWrHTtkw/graphicsinterface)
+* [Issue Tracker](https://github.com/HopsonCommunity/GraphicsInterface/issues)
+
+### Story Editor
+
+* [Git Repository](https://github.com/HopsonCommunity/TextAdventureEditor)
+* [Agile Board](https://trello.com/b/rb2aTrnY/textadventureeditor)
+* [Issue Tracker](https://github.com/HopsonCommunity/TextAdventureEditor/issues)
+
+### Misc Tools
+
+* [Binary Files Storage]()
+* [Discord Online Chat](https://discord.gg/F6WF7Dm)
+
+## See also:
+
+* [Contirbution Guidelines & Contributor Info](docs/CONTRIBUTING.md)
+* [Engine Explained](docs/EXPLAINED.md)
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,155 @@
+# Contributing Guidelines & Contributor Info
+
+Welcome to Contributing Guidelines for Hopson's Community Text Adventure project.
+
+First and foremost, if you consider doing more than few simple edits, please join us at the [Discord Server](https://discord.gg/F6WF7Dm) and request a Community Project role.
+
+Project has several parts as documented in the [README](../README.md). Project is developed in Python 3.
+
+See also [Engine Explained](EXPLAINED.md).
+
+## Programming:
+
+* [Style](https://www.python.org/dev/peps/pep-0008/)
+* 4 spaces indentation level
+* 2 empty lines before functions
+* [Git branching](http://nvie.com/posts/a-successful-git-branching-model/)
+* [Git commit messages](https://chris.beams.io/posts/git-commit/)
+* In GitHub, fork your own copy of the repo you plan to work on, and use feature branches in the fork to PR back.
+
+### Story Editor:
+
+* [TkInter](https://wiki.python.org/moin/TkInter)?
+* [GTK+](http://www.pygtk.org/)?
+* [Kivy](https://kivy.org/)?
+
+Select a directory for all assets (music, background, …)
+
+Use placeholder, instead of referring the path, to make future change easier
+
+### Story Engine:
+
+* Data storage
+* Interpreting story files
+* Inventory       
+* Player stats
+* State transition / map stuff
+
+**Potential pseudocode of state:** (not final)
+
+```
+enter_state: 
+    draw bg
+    play music
+    print title
+    print text
+    for each opt from options
+        if opt.all_requires_ok
+            print opt
+        else if not opt.hide
+            print opt in disable mode
+    wait until click on option
+        goto option.next_state
+```
+
+#### Data:
+
+* Custom format for storing stories ("gamebooks"), common archive (zip?) with custom extension (book?)
+* Entry file for each story
+* Story define as json file
+* Recursively walk the directory and load everything into a single dict.
+* Alternatively a single json.
+
+**Example story structure:** (not final)
+
+```
+adventure.book (zip archive)
+	config.json
+	Village
+		Townhall
+			state1.json
+			state2.json
+		Bank
+			Entrance.json
+			Vault.json
+```
+
+**Example state code:** (not final, short examples showing specific uses)
+
+```json
+"entrance": {
+    "text": "You're at the haunted house entrance.",
+    "gotos": [
+        {"description": "Pick the Key", "state": "entrance", "requirements": {"rusty key": 0}, "acquire": {"rusty key": 1}},
+        {"description": "Open the Door", "state": "inside", "requirements": {"rusty key": 1}, "hide": {"rusty key": 1}}
+    ]
+},
+"inside": {
+    "text": "The ghosts spook this place.",
+    "gotos": […]
+}
+```
+
+```json
+"outside-pub" : {
+	"text": "You're outside pub, Jack's sitting on the bench.",
+	"gotos": [
+		{"description": "Talk to Jack", "state": "introduction-jack", "requirements": {"knows Jack": false}},
+		{"description": "Talk to Jack", "state": "chatter-jack", "requirements": {"knows Jack": true}}
+	]
+},
+"introduction-jack": {
+    "text": "Hi, I'm Jack, who are you?",
+    "gotos": [
+        {"description": "Hey, I'm Eremiell!", "state": "chatter-jack", "acquire": {"knows Jack": true}}
+    ]
+},
+"chatter-jack": {
+    "text": "How can I help you today?",
+    "gotos": [
+        {"description": "I need some help with Python", "state": "python-hax-jack"},
+        {"description": "Fancy a glass of whiskey?", "state": "whiskey-with-jack"},
+        {"description": "Ah, not really. Still nice to see you.", "state": "outside-pub"}
+    ]
+}
+```
+
+[Longer, more complex example](example.json)
+
+### Graphics engine:
+
+* **Graphical library** - [pyglet](https://bitbucket.org/pyglet/pyglet/wiki/Home)
+
+### Programming reference:
+
+* [Python 3](https://docs.python.org/3/)
+* [Pyglet](https://pyglet.readthedocs.io/en/pyglet-1.3-maintenance/)
+* [PEP-8](https://www.python.org/dev/peps/pep-0008/)
+* [PEP-257](https://www.python.org/dev/peps/pep-0257/)
+* [JSON](http://json.org/)
+
+### Other:
+
+#### Sounds:
+
+* Play sounds upon entering a state.
+* Play sounds when selecting an option.
+
+## Art:
+
+### Visual Art reference:
+
+* [westerando_big](http://games.gameshed.com/westerando_big.jpg)
+* [cowboy-with-rifle](https://opengameart.org/content/cowboy-with-rifle)
+* [cowboy-with-revolver](https://opengameart.org/content/cowboy-with-revolver)
+* [cowboy](https://opengameart.org/content/cowboy)
+* [fistful-of-gun](https://gamejolt.com/games/fistful-of-gun/16749)
+* [cowboy-game-sprites](https://opengameart.org/content/cowboy-game-sprites)
+
+### Audio Art reference:
+
+* [Ennio Morricone](https://www.youtube.com/watch?v=9dpNQFpeo6U)
+* [8-bit Western](https://www.youtube.com/watch?v=a3AlfkiVeIM)
+* [Fastest Gun in 8-bit West](https://www.youtube.com/watch?v=WDdZLk7pRfI)
+* [The Haunted West](https://www.youtube.com/watch?v=prT7PCMF8_Q)
+* [Summertime Cowboy](https://www.youtube.com/watch?v=nu-261SVh-c)
diff --git a/docs/EXPLAINED.md b/docs/EXPLAINED.md
@@ -0,0 +1,36 @@
+# Engine Explained
+
+The engine follows the logic of text adventures, especially those appearing in form of so called gamebooks around 90s.
+
+The story is built from states, that allow the players some options, each option moving them into further states and potentially having other side-effects (item pickup, stats change, …).
+
+The engine reads those stories from archives called books, that contain the story formatted into a common storage format known as JSON, as well as it's assets. The whole story comes to the player in form of this single book file.
+
+The player is then presented with various states and options as described by the story in the book they loaded.
+
+## More in depth explanation including some special uses useful for creating new stories
+
+![flow](https://imgur.com/ggmYiZS.png)
+
+Diagram describing the flow between different scenes inside the engine.
+
+Each scene has a number of options that user may choose in order to progress to the next or previous scenes.
+
+![dialogue](https://imgur.com/TsTGrXH.png)
+
+This basic concept allows you to not only describe the movement of the player in the physical realm but also to represent dialogue trees and fight scenes.
+
+![item_pickup](https://imgur.com/4WViyOA.png)
+
+This image shows a method of acquiring items using loopbacks to the same scene.
+
+You are in the left state called "Dungeon" and are presented with two choices.
+
+* Pick up sword
+* Go left
+
+Upon selecting "Pick up sword", the engine will add the sword to your player and effectively reload the scene.
+
+This time when the scene is presented, the "Pick up sword" option is no longer displayed because it only displays if a condition is met, the condition being: you must have no swords on your person.
+
+The user only has one remaining choice and that is to continue on, as shown in the box on the right side of the diagram.
diff --git a/docs/example.json b/docs/example.json
@@ -0,0 +1,127 @@
+config = {
+    "name" : "Dungeon Quest Extreme V2",
+    "description" : "A quest through all of space and time.",
+
+    "starting_scene" : "entrance",  // the entry point of the story.
+
+                                    // parent folders for various config files.
+    "items"  : "story/items/",      // check "items = " below.
+    "stats"  : "story/stats/",      // check "stats = " below.
+    "assets" : "story/assets/",     // check "assets = " below.
+    "scenes" : "story/scenes/",     // check "scenes = " below.
+
+                                    // meta data about author.
+    "meta" : {  
+        "author" : "Jack",
+        "url" : "rms.org",
+        "email" : "[email protected]"
+    }
+}
+
+
+
+items = {
+    "bronze_key_1" : { // item id and basic meta data.
+        "name" : "Bronze Key",
+        "description" : "A bronze key."
+    },
+
+    "red_key_1" : {
+        "name" : "Red Key",
+        "description" : "A red key with a firey pattern."
+    }    
+}
+
+
+
+stats = {
+    "traits" : { // stats and abilities you can obtain or change depending on the choices you make.
+        "morality" : {
+            "name" : "Morality",
+            "description" : "Not being a dick."
+        },
+
+        "kindness" : {
+            "name" : "Kindness",
+            "description" : "Being not a dick."
+        },
+
+        "power_of_zeus" : {
+            "name" : "Zeus himself",
+            "description" : "Shoot shit with lightning."
+        }
+    },
+
+    "classes" : { // default classes.
+        "murderer" : {
+            "morality" : -100,
+            "kindness" : -100,
+            "power_of_zeus" : 3
+        },
+
+        "archer" : {
+            "morality" : 10,
+            "kindness" : 5,
+            "power_of_zeus" : 666
+        }
+    }
+}
+
+
+assets = {
+    "dungeon_ambiance" : {
+        "music"   : "wonderwall.wav",    // music to play when scene is active.
+        "bg"      : "dungeon_wall.jpg",  // background picture to show.
+        "sprites" : [
+            {
+                "file" : "ciaran.jpg",   // the file to load.
+                "position" : [200, 400], // where on screen to position the sprite.
+                "size" : 1               // size multiplier. 1 = same as file
+            },
+
+            {
+                "file" : "god.jpg",      // the file to load.
+                "position" : [700, 400], // where on screen to position the sprite.
+                "size" : 2               // size multiplier. 1 = same as file
+            },
+        ]
+    }
+}
+
+
+scenes = {
+    "entrance" : {
+        "title" : "The Dungeon",                       // human readable name
+        "description" : "Welcome to hell, you swine.", // description of your surroundings, exposition.
+
+        "assets" : "dungeon_ambiance",                 // if assets are the same as last scene, 
+                                                       // dont reload anything, just reuse and continue music etc
+
+        "end" : false,                                 // is this scene an endstate?
+
+        "gotos" : [
+            {
+                "label" : "Pick up bronze key.",       // human readable form.
+                "scene" : "entrance",                  // loop back to the same room.
+
+                "stats" : {                            // stat alterations made by picking this option.
+                    "morality" : 10,                   // add ten morality.
+                    "kindness" : -5,                   // remove 5 kindness.
+                    "power_of_zeus" : 200              // give you some ass kicking power.
+                },      
+
+                "history" : {                          // variables to keep track of during gameplay.
+                    "knows_jack" : true                // the player has encountered the npc called jack previously.
+                },      
+
+                "acquire" : {                          // allow the user to pick up the key.
+                    "bronze_key_1" : 1                 // pick up one key.
+                },
+
+                "require" : {                          // if the user has this item, hide this option from the list.
+                    "bronze_key_1" : 0                 // requires 0 of these items, e.g: you have to have none.
+                }
+            }
+        ]
+    }
+}