From a4661e59cbe47119621db569a83b4bd4b6547832 Mon Sep 17 00:00:00 2001 From: Jakub 'Eremiell' Marek Date: Thu, 21 Dec 2017 03:17:55 +0100 Subject: [PATCH] Adds initial docs. --- README.md | 44 +++++++++++- docs/CONTRIBUTING.md | 155 +++++++++++++++++++++++++++++++++++++++++++ docs/EXPLAINED.md | 36 ++++++++++ docs/example.json | 127 +++++++++++++++++++++++++++++++++++ 4 files changed, 359 insertions(+), 3 deletions(-) create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/EXPLAINED.md create mode 100644 docs/example.json diff --git a/README.md b/README.md index edc70e4..62f34aa 100644 --- 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) \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..11a2b02 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/EXPLAINED.md b/docs/EXPLAINED.md new file mode 100644 index 0000000..62b2eba --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/example.json b/docs/example.json new file mode 100644 index 0000000..4883470 --- /dev/null +++ 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" : "nou@oboforty.com" + } +} + + + +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. + } + } + ] + } +} \ No newline at end of file