From af5884705e466ec36a8b6a20dc2a950c0ecef454 Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 19 Jun 2020 22:20:17 +0200 Subject: [PATCH] Start refactor howtos --- docs/source/Evennia-Introduction.md | 2 +- docs/source/Howto/Howto-Overview.md | 91 +++++++++++++++++-- .../Learn-Python-for-Evennia-The-Hard-Way.md | 70 -------------- .../Howto/Starting/Coding-Introduction.md | 2 +- .../Howto/{ => Starting}/Coordinates.md | 2 +- .../Howto/{ => Starting}/Game-Planning.md | 6 +- .../Implementing-a-game-rule-system.md | 4 +- docs/source/Setup/Setup-Quickstart.md | 11 +-- docs/source/toc.md | 10 +- 9 files changed, 102 insertions(+), 96 deletions(-) delete mode 100644 docs/source/Howto/Learn-Python-for-Evennia-The-Hard-Way.md rename docs/source/Howto/{ => Starting}/Coordinates.md (99%) rename docs/source/Howto/{ => Starting}/Game-Planning.md (97%) rename docs/source/Howto/{ => Starting}/Implementing-a-game-rule-system.md (98%) diff --git a/docs/source/Evennia-Introduction.md b/docs/source/Evennia-Introduction.md index 6975dd2850..5ff987794c 100644 --- a/docs/source/Evennia-Introduction.md +++ b/docs/source/Evennia-Introduction.md @@ -175,7 +175,7 @@ chat](http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9 on IRC. This allows you to chat directly with other developers new and old as well as with the devs of Evennia itself. This chat is logged (you can find links on http://www.evennia.com) and can also be searched from the same place for discussion topics you are interested in. -2. Read the [Game Planning](Howto/Game-Planning) wiki page. It gives some ideas for your work flow and the +2. Read the [Game Planning](Howto/Starting/Game-Planning) wiki page. It gives some ideas for your work flow and the state of mind you should aim for - including cutting down the scope of your game for its first release. 3. Do the [Tutorial for basic MUSH-like game](Howto/Starting/Tutorial-for-basic-MUSH-like-game) carefully from diff --git a/docs/source/Howto/Howto-Overview.md b/docs/source/Howto/Howto-Overview.md index 6d94c15446..163aa26a19 100644 --- a/docs/source/Howto/Howto-Overview.md +++ b/docs/source/Howto/Howto-Overview.md @@ -6,20 +6,97 @@ a particular feature or concept. They will often refer to the [components](Components/Components-Overview) or [concepts](Concepts/Concepts-Overview) docs for those that want to dive deeper. -## Starting Tutorial +## The Starting Tutorial Recommended starting point! This will take you from absolute beginner to making a small, but full, game with Evennia. Even if you have a very different game style in mind for your own game, this will give you a good start. +### Part 1: What we have -```warning:: +- [Introduction & Overview](Starting/Starting-Overview) +- [Building stuff](Starting/Building-Quickstart) +- [Python basics](Starting/Python-basic-introduction) +- [Python classes](Starting/Python-basic-tutorial-part-two) +- [Running Python in- and outside the game](Starting/Execute-Python-Code) +- [Understanding errors](Understanding-Errors) +- [Searching for things](Starting/Tutorial-Searching-For-Objects) +- [A walkthrough of the API](Walkthrough-of-API) - The Starting tutorial is still under development. +### Part 2: What we want -``` +- [On planning a game](Starting/Game-Planning) +- [Multisession modes](Multi-session-modes) +- [Layout of our tutorial game](Game-Tutorial-Planning) +- [Making use of contribs](Using-Contribs) -- [Introduction & Overview](Howto/Starting-Overvew) - +### Part3: How we get there -## +- [Where to put code](Starting/First-Steps-Coding) +- [Adding a first command](Starting/Adding-Command-Tutorial) +- [Parsing strings](Starting/Parsing-command-arguments,-theory-and-best-practices) +- [Making a custom Character](Starting/Adding-Object-Typeclass-Tutorial) +- [The rules of the game](Starting/Implementing-a-game-rule-system) +- [Character generation](Character-Generkation) +- [Resolving skills and challenges](Skills-and-Challenges) +- [NPCs and mobiles](NPCs-and-Mobiles) +- [On grids and coordinates](Starting/Coordinates) +- [Quests and Zones](Quests-and-Zones) +- [A Combat system](Combat-System) + +### Part4: Using what we created + +- [Building the tech demo](Building-the-tech-demo) +- [Creating a game world](Creating-a-game-world) + +### Part6: Showing the world + +- [Add a web page](Starting/Add-a-simple-new-web-page) +- [More on adding web features](Starting/Web-Tutorial) +- [Taking your game online](Taking-your-game-online) +- [Next steps](Where-to-Go-from-here) + + +## FAQs + +- [Coding FAQ](Coding-FAQ) + +## Howto's + +- [Giving Exits a default error](Default-Exit-Errors) +- [Customize Channel output](Customize-channels) +- [Add a command prompt](Command-Prompt) +- [Don't allow spamming commands](Command-Cooldown) +- [Commands that take time](Command-Duration) +- [Configuring color](Manually-Configuring-Color) +- [Tweet game stats](Tutorial-Tweeting-Game-Stats) + +## Mobs and NPCs + +- [NPCs that listen to you](Tutorial-NPCs-listening) +- [Mobs that attack you](Tutorial-Aggressive-NPCs) +- [Shopkeepers](NPC-shop-Tutorial) + +## Vehicles + +- [Building a mech](Building-a-mech-tutorial) +- [Building a train](Tutorial-Vehicles) + +## Systems + +- [Understanding In-game time](Gametime-Tutorial) +- [Understanding the Help system](Help-System-Tutorial) +- [Adding mass to objects](Mass-and-weight-for-objects) +- [Add weather](Weather-Tutorial) + +## Web-related tutorials + +- [Add a wiki](Add-a-wiki-on-your-website) +- [A web-based character generation](Web-Character-Generation) +- [View Character on website](Web-Character-View-Tutorial) + +## Deep-dives +- [Understanding color-tags](Understanding-Color-Tags) +- [Play paper&pen RPGs online with Evennia](Evennia-for-roleplaying-sessions) +- [Evennia for Diku Users](Evennia-for-Diku-Users) +- [Evennia for MUSH-Users](Evennia-for-MUSH-Users) diff --git a/docs/source/Howto/Learn-Python-for-Evennia-The-Hard-Way.md b/docs/source/Howto/Learn-Python-for-Evennia-The-Hard-Way.md deleted file mode 100644 index 1d79026106..0000000000 --- a/docs/source/Howto/Learn-Python-for-Evennia-The-Hard-Way.md +++ /dev/null @@ -1,70 +0,0 @@ -# Learn Python for Evennia The Hard Way - -# WORK IN PROGRESS - DO NOT USE - -Evennia provides a great foundation to build your very own MU* whether you have programming -experience or none at all. Whilst Evennia has a number of in-game building commands and tutorials -available to get you started, when approaching game systems of any complexity it is advisable to -have the basics of Python under your belt before jumping into the code. There are many Python -tutorials freely available online however this page focuses on Learn Python the Hard Way (LPTHW) by -Zed Shaw. This tutorial takes you through the basics of Python and progresses you to creating your -very own online text based game. Whilst completing the course feel free to install Evennia and try -out some of our beginner tutorials. On completion you can return to this page, which will act as an -overview to the concepts separating your online text based game and the inner-workings of Evennia. --The latter portion of the tutorial focuses working your engine into a webpage and is not strictly -required for development in Evennia. - -## Exercise 23 -You may have returned here when you were invited to read some code. If you haven’t already, you -should now have the knowledge necessary to install Evennia. Head over to the Getting Started page -for install instructions. You can also try some of our tutorials to get you started on working with -Evennia. - -## Bridging the gap. -If you have successfully completed the Learn Python the Hard Way tutorial you should now have a -simple browser based Interactive Fiction engine which looks similar to this. -This engine is built using a single interactive object type, the Room class. The Room class holds a -description of itself that is presented to the user and a list of hardcoded commands which if -selected correctly will present you with the next rooms’ description and commands. Whilst your game -only has one interactive object, MU* have many more: Swords and shields, potions and scrolls or even -laser guns and robots. Even the player has an in-game representation in the form of your character. -Each of these examples are represented by their own object with their own description that can be -presented to the user. - -A basic object in Evennia has a number of default functions but perhaps most important is the idea -of location. In your text engine you receive a description of a room but you are not really in the -room because you have no in-game representation. However, in Evennia when you enter a Dungeon you -ARE in the dungeon. That is to say your character.location = Dungeon whilst the Dungeon.contents now -has a spunky young adventurer added to it. In turn, your character.contents may have amongst it a -number of swords and potions to help you on your adventure and their location would be you. - -In reality each of these “objects” are just an entry in your Evennia projects database which keeps -track of all these attributes, such as location and contents. Making changes to those attributes and -the rules in which they are changed is the most fundamental perspective of how your game works. We -define those rules in the objects Typeclass. The Typeclass is a Python class with a special -connection to the games database which changes values for us through various class methods. Let’s -look at your characters Typeclass rules for changing location. - - 1. `self.at_before_move(destination)` (if this returns False, move is aborted) - 2. `self.announce_move_from(destination)` - 3. (move happens here) - 4. `self.announce_move_to(source_location)` - 5. `self.at_after_move(source_location)` - -First we check if it’s okay to leave our current location, then we tell everyone there that we’re -leaving. We move locations and tell everyone at our new location that we’ve arrived before checking -we’re okay to be there. By default stages 1 and 5 are empty ready for us to add some rules. We’ll -leave an explanation as to how to make those changes for the tutorial section, but imagine if you -were an astronaut. A smart astronaut might stop at step 1 to remember to put his helmet on whilst a -slower astronaut might realise he’s forgotten in step 5 before shortly after ceasing to be an -astronaut. - -With all these objects and all this moving around it raises another problem. In your text engine the -commands available to the player were hard-coded to the room. That means if we have commands we -always want available to the player we’ll need to have those commands hard-coded on every single -room. What about an armoury? When all the swords are gone the command to take a sword would still -remain causing confusion. Evennia solves this problem by giving each object the ability to hold -commands. Rooms can have commands attached to them specific to that location, like climbing a tree; -Players can have commands which are always available to them, like ‘look’, ‘get’ and ‘say’; and -objects can have commands attached to them which unlock when taking possession of it, like attack -commands when obtaining a weapon. \ No newline at end of file diff --git a/docs/source/Howto/Starting/Coding-Introduction.md b/docs/source/Howto/Starting/Coding-Introduction.md index bbef668d6a..7a71ac39ba 100644 --- a/docs/source/Howto/Starting/Coding-Introduction.md +++ b/docs/source/Howto/Starting/Coding-Introduction.md @@ -52,7 +52,7 @@ using such a checker can be a good start to weed out the simple problems. ### Plan before you code -Before you start coding away at your dream game, take a look at our [Game Planning](../Game-Planning) +Before you start coding away at your dream game, take a look at our [Game Planning](Game-Planning) page. It might hopefully help you avoid some common pitfalls and time sinks. ### Code in your game folder, not in the evennia/ repository diff --git a/docs/source/Howto/Coordinates.md b/docs/source/Howto/Starting/Coordinates.md similarity index 99% rename from docs/source/Howto/Coordinates.md rename to docs/source/Howto/Starting/Coordinates.md index d46ff14096..5d469de667 100644 --- a/docs/source/Howto/Coordinates.md +++ b/docs/source/Howto/Starting/Coordinates.md @@ -23,7 +23,7 @@ instance. ## Coordinates as tags The first concept might be the most surprising at first glance: we will create coordinates as -[tags](../Component/Tags). +[tags](../../Component/Tags). > Why not attributes, wouldn't that be easier? diff --git a/docs/source/Howto/Game-Planning.md b/docs/source/Howto/Starting/Game-Planning.md similarity index 97% rename from docs/source/Howto/Game-Planning.md rename to docs/source/Howto/Starting/Game-Planning.md index a17a3829ed..1af061fa0a 100644 --- a/docs/source/Howto/Game-Planning.md +++ b/docs/source/Howto/Starting/Game-Planning.md @@ -132,7 +132,7 @@ Talker-type game you *will* have to bite the bullet and code your game (or find do it for you). Even if you won't code anything yourself, as a designer you need to at least understand the basic -paradigms of Evennia, such as [Objects](../Component/Objects), [Commands](../Component/Commands) and [Scripts](../Component/Scripts) and +paradigms of Evennia, such as [Objects](../../Component/Objects), [Commands](../../Component/Commands) and [Scripts](../../Component/Scripts) and how they hang together. We recommend you go through the [Tutorial World](Tutorial-World- Introduction) in detail (as well as glancing at its code) to get at least a feel for what is involved behind the scenes. You could also look through the tutorial for [building a game from @@ -144,7 +144,7 @@ The earlier you revise problems, the easier they will be to fix. A good idea is to host your code online (publicly or privately) using version control. Not only will this make it easy for multiple coders to collaborate (and have a bug-tracker etc), it also means -your work is backed up at all times. The [Version Control](../Coding/Version-Control) tutorial has +your work is backed up at all times. The [Version Control](../../Coding/Version-Control) tutorial has instructions for setting up a sane developer environment with proper version control. ### "Tech Demo" Building @@ -199,7 +199,7 @@ flag and let people try it! Call upon your alpha-players to try everything - the to break your game in ways that you never could have imagined. In Alpha you might be best off to focus on inviting friends and maybe other MUD developers, people who you can pester to give proper feedback and bug reports (there *will* be bugs, there is no way around it). Follow the quick -instructions for [Online Setup](../Setup/Online-Setup) to make your game visible online. If you hadn't +instructions for [Online Setup](../../Setup/Online-Setup) to make your game visible online. If you hadn't already, make sure to put up your game on the [Evennia game index](http://games.evennia.com/) so people know it's in the works (actually, even pre-alpha games are allowed in the index so don't be shy)! diff --git a/docs/source/Howto/Implementing-a-game-rule-system.md b/docs/source/Howto/Starting/Implementing-a-game-rule-system.md similarity index 98% rename from docs/source/Howto/Implementing-a-game-rule-system.md rename to docs/source/Howto/Starting/Implementing-a-game-rule-system.md index 855051aae3..c88294551e 100644 --- a/docs/source/Howto/Implementing-a-game-rule-system.md +++ b/docs/source/Howto/Starting/Implementing-a-game-rule-system.md @@ -45,12 +45,12 @@ makes it easier to change and update things in one place later. values for Health, a list of skills etc, store those things on the Character - don't store how to roll or change them. - Next is to determine just how you want to store things on your Objects and Characters. You can -choose to either store things as individual [Attributes](../Component/Attributes), like `character.db.STR=34` and +choose to either store things as individual [Attributes](../../Component/Attributes), like `character.db.STR=34` and `character.db.Hunting_skill=20`. But you could also use some custom storage method, like a dictionary `character.db.skills = {"Hunting":34, "Fishing":20, ...}`. A much more fancy solution is to look at the Ainneve [Trait handler](https://github.com/evennia/ainneve/blob/master/world/traits.py). Finally you could even go -with a [custom django model](../Concept/New-Models). Which is the better depends on your game and the +with a [custom django model](../../Concept/New-Models). Which is the better depends on your game and the complexity of your system. - Make a clear [API](http://en.wikipedia.org/wiki/Application_programming_interface) into your rules. That is, make methods/functions that you feed with, say, your Character and which skill you diff --git a/docs/source/Setup/Setup-Quickstart.md b/docs/source/Setup/Setup-Quickstart.md index 8a21c48139..dc321a6f77 100644 --- a/docs/source/Setup/Setup-Quickstart.md +++ b/docs/source/Setup/Setup-Quickstart.md @@ -7,16 +7,15 @@ in complete isolation if you want, without needing any access to the internet. ## Installation Evennia requires Python3.7+. As with most Python packages, using a -[virtualenv](../Glossary#Virtualenv) is recommended in order to keep your +[virtualenv](../Glossary#virtualenv) is recommended in order to keep your installation independent from the system libraries. It's _not_ recommended to install Evennia as superuser. pip install evennia -If things worked, the `evennia` command should now be available. Use `evennia -h` for -usage help (or read on). +Make sure the `evennia` command works. Use `evennia -h` for usage help (or read on). -If you are having trouble, want to install in some other way (like with Docker) or want to help develop +If you are having trouble, want to install in some other way (like with Docker) or want to contribute to Evennia itself, check out the [Extended Installation instructions](Extended-Installation). It also has a [troubleshooting section](Extended-Installation#Troubleshooting) for different operating systems. @@ -50,7 +49,7 @@ Fill in your user-name and password. This will be the "god user" or "superuser" If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game! -> If `localhost` doesn't work on your computer, use `127.0.0.1`, which it's the same thing. +> If `localhost` doesn't work on your computer, use `127.0.0.1`, which is the same thing. ## See server logs @@ -88,4 +87,4 @@ Stop the server (will need to use `start` to activate it again): ## The Next step -Why not head into the [Starting Tutorial] to learn how to start making your new game. +Why not head into the [Starting Tutorial](../Howto/Starting/Starting-Overview) to learn how to start making your new game! diff --git a/docs/source/toc.md b/docs/source/toc.md index e696f10549..8d70d4741e 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -77,17 +77,14 @@ - [Howto/Command Cooldown](Howto/Command-Cooldown) - [Howto/Command Duration](Howto/Command-Duration) - [Howto/Command Prompt](Howto/Command-Prompt) -- [Howto/Coordinates](Howto/Coordinates) - [Howto/Customize channels](Howto/Customize-channels) - [Howto/Default Exit Errors](Howto/Default-Exit-Errors) - [Howto/Evennia for Diku Users](Howto/Evennia-for-Diku-Users) - [Howto/Evennia for MUSH Users](Howto/Evennia-for-MUSH-Users) - [Howto/Evennia for roleplaying sessions](Howto/Evennia-for-roleplaying-sessions) -- [Howto/Game Planning](Howto/Game-Planning) - [Howto/Gametime Tutorial](Howto/Gametime-Tutorial) - [Howto/Help System Tutorial](Howto/Help-System-Tutorial) -- [Howto/Implementing a game rule system](Howto/Implementing-a-game-rule-system) -- [Howto/Learn Python for Evennia The Hard Way](Howto/Learn-Python-for-Evennia-The-Hard-Way) +- [Howto/Howto Overview](Howto/Howto-Overview) - [Howto/Manually Configuring Color](Howto/Manually-Configuring-Color) - [Howto/Mass and weight for objects](Howto/Mass-and-weight-for-objects) - [Howto/NPC shop Tutorial](Howto/NPC-shop-Tutorial) @@ -96,12 +93,15 @@ - [Howto/Starting/Adding Object Typeclass Tutorial](Howto/Starting/Adding-Object-Typeclass-Tutorial) - [Howto/Starting/Building Quickstart](Howto/Starting/Building-Quickstart) - [Howto/Starting/Coding Introduction](Howto/Starting/Coding-Introduction) +- [Howto/Starting/Coordinates](Howto/Starting/Coordinates) - [Howto/Starting/Execute Python Code](Howto/Starting/Execute-Python-Code) - [Howto/Starting/First Steps Coding](Howto/Starting/First-Steps-Coding) +- [Howto/Starting/Game Planning](Howto/Starting/Game-Planning) +- [Howto/Starting/Implementing a game rule system](Howto/Starting/Implementing-a-game-rule-system) - [Howto/Starting/Parsing command arguments, theory and best practices](Howto/Starting/Parsing-command-arguments,-theory-and-best-practices) - [Howto/Starting/Python basic introduction](Howto/Starting/Python-basic-introduction) - [Howto/Starting/Python basic tutorial part two](Howto/Starting/Python-basic-tutorial-part-two) -- [Howto/Starting/Starting Introduction](Howto/Starting/Starting-Introduction) +- [Howto/Starting/Starting Overview](Howto/Starting/Starting-Overview) - [Howto/Starting/Turn based Combat System](Howto/Starting/Turn-based-Combat-System) - [Howto/Starting/Tutorial Searching For Objects](Howto/Starting/Tutorial-Searching-For-Objects) - [Howto/Starting/Tutorial for basic MUSH like game](Howto/Starting/Tutorial-for-basic-MUSH-like-game)