From c4dc5541792b16d9697bacaae679ba5a77d69050 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sat, 20 Jun 2020 19:37:09 +0200 Subject: [PATCH] Add more tutorial steps --- docs/source/Contrib/Contrib-Overview.md | 2 +- .../Contrib/Tutorial-World-Introduction.md | 106 ------------ docs/source/Evennia-Introduction.md | 2 +- .../Howto/Starting/Building-Quickstart.md | 163 +++++++++++------- docs/source/Howto/Starting/Starting-Part1.md | 94 +++++++++- .../Starting/Tutorial-World-Introduction.md | 119 +++++++++++++ .../Tutorial-for-basic-MUSH-like-game.md | 2 +- docs/source/Setup/Extended-Installation.md | 2 +- docs/source/_static/nature.css | 4 +- docs/source/toc.md | 2 +- 10 files changed, 314 insertions(+), 182 deletions(-) delete mode 100644 docs/source/Contrib/Tutorial-World-Introduction.md create mode 100644 docs/source/Howto/Starting/Tutorial-World-Introduction.md diff --git a/docs/source/Contrib/Contrib-Overview.md b/docs/source/Contrib/Contrib-Overview.md index 4f55b62426..a0a42f58d7 100644 --- a/docs/source/Contrib/Contrib-Overview.md +++ b/docs/source/Contrib/Contrib-Overview.md @@ -15,7 +15,7 @@ longer-form documentation associated with particular contribs. ## The tutorial-world -- [The tutorial world introduction](Tutorial-World-Introduction) +- [The tutorial world introduction](../Howto/Starting/Tutorial-World-Introduction) ## Menu-builder diff --git a/docs/source/Contrib/Tutorial-World-Introduction.md b/docs/source/Contrib/Tutorial-World-Introduction.md deleted file mode 100644 index 21eec7416f..0000000000 --- a/docs/source/Contrib/Tutorial-World-Introduction.md +++ /dev/null @@ -1,106 +0,0 @@ -# Tutorial World Introduction - - -The *Tutorial World* is a small and functioning MUD-style game world. It is intended to be -deconstructed and used as a way to learn Evennia. The game consists of a single-player quest and -has some 20 rooms that you can explore as you seek to discover the whereabouts of a mythical weapon. - -The source code is fully documented. You can find the whole thing in -`evennia/contrib/tutorial_world/`. - -Some features exemplified by the tutorial world: - -- Tutorial command, giving "behind-the-scenes" help for every room and some of the special objects -- Rooms with custom `return_appearance` to show details. -- Hidden exits -- Objects with multiple custom interactions -- Large-area rooms -- Outdoor weather rooms -- Dark room, needing light source -- Puzzle object -- Multi-room puzzle -- Aggressive mobile with roam, pursue and battle state-engine AI -- Weapons, also used by mobs -- Simple combat system with attack/defend commands -- Object spawning -- Teleporter trap rooms - - -## Install - -The tutorial world consists of a few modules in `evennia/contrib/tutorial_world/` containing custom -[Typeclasses](../Component/Typeclasses) for [rooms and objects](../Component/Objects) and associated [Commands](../Component/Commands). - -These reusable bits and pieces are then put together into a functioning game area ("world" is maybe -too big a word for such a small zone) using a [batch script](../Component/Batch-Processors) called `build.ev`. To -install, log into the server as the superuser (user #1) and run: - - @batchcommand tutorial_world.build - -The world will be built (this might take a while, so don't rerun the command even if it seems the -system has frozen). After finishing you will end up back in Limbo with a new exit called `tutorial`. - -An alternative is - - @batchcommand/interactive tutorial_world.build - -with the /interactive switch you are able to step through the building process at your own pace to -see what happens in detail. - -To play the tutorial "correctly", you should *not* do so as superuser. The reason for this is that -many game systems ignore the presence of a superuser and will thus not work as normal. Use the -`@quell` command to limit your powers or log out and reconnect as a different user. As superuser you -can of course examine things "under the hood" later if you want. - -## Gameplay - -![the castle off the moor](https://images-wixmp- -ed30a86b8c4ca887773594c2.wixmp.com/f/22916c25-6299-453d-a221-446ec839f567/da2pmzu-46d63c6d-9cdc-41dd-87d6-1106db5a5e1a.jpg/v1/fill/w_600,h_849,q_75,strp/the_castle_off_the_moor_by_griatch_art_da2pmzu- -fullview.jpg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOiIsImlzcyI6InVybjphcHA6Iiwib2JqIjpbW3siaGVpZ2h0IjoiPD04NDkiLCJwYXRoIjoiXC9mXC8yMjkxNmMyNS02Mjk5LTQ1M2QtYTIyMS00NDZlYzgzOWY1NjdcL2RhMnBtenUtNDZkNjNjNmQtOWNkYy00MWRkLTg3ZDYtMTEwNmRiNWE1ZTFhLmpwZyIsIndpZHRoIjoiPD02MDAifV1dLCJhdWQiOlsidXJuOnNlcnZpY2U6aW1hZ2Uub3BlcmF0aW9ucyJdfQ.omuS3D1RmFiZCy9OSXiIita- -HxVGrBok3_7asq0rflw) - - -*To get into the mood of this miniature quest, imagine you are an adventurer out to find fame and -fortune. You have heard rumours of an old castle ruin by the coast. In its depth a warrior princess -was buried together with her powerful magical weapon - a valuable prize, if it's true. Of course -this is a chance to adventure that you cannot turn down!* - -*You reach the ocean in the midst of a raging thunderstorm. With wind and rain screaming in your -face you stand where the moor meets the sea along a high, rocky coast ...* - -- Look at everything. -- Some objects are interactive in more than one way. Use the normal `help` command to get a feel for -which commands are available at any given time. (use the command `tutorial` to get insight behind -the scenes of the tutorial). - -- In order to fight, you need to first find some type of weapon. -- *slash* is a normal attack -- *stab* launches an attack that makes more damage but has a lower chance to hit. -- *defend* will lower the chance to taking damage on your enemy's next attack. -- You *can* run from a fight that feels too deadly. Expect to be chased though. -- Being defeated is a part of the experience ... - -## Uninstall - -Uninstalling the tutorial world basically means deleting all the rooms and objects it consists of. -First, move out of the tutorial area. - - @find tut#01 - @find tut#16 - -This should locate the first and last rooms created by `build.ev` - *Intro* and *Outro*. If you -installed normally, everything created between these two numbers should be part of the tutorial. -Note their dbref numbers, for example 5 and 80. Next we just delete all objects in that range: - - @del 5-80 - -You will see some errors since some objects are auto-deleted and so cannot be found when the delete -mechanism gets to them. That's fine. You should have removed the tutorial completely once the -command finishes. - -## Notes - -When reading and learning from the code, keep in mind that *Tutorial World* was created with a very -specific goal: to install easily and to not permanently modify the rest of the server. It therefore -goes to some length to use only temporary solutions and to clean up after -itself. \ No newline at end of file diff --git a/docs/source/Evennia-Introduction.md b/docs/source/Evennia-Introduction.md index 5ff987794c..614599176f 100644 --- a/docs/source/Evennia-Introduction.md +++ b/docs/source/Evennia-Introduction.md @@ -47,7 +47,7 @@ a [screenshot](Screenshot). Once you installed Evennia yourself it comes with its own tutorial - this shows off some of the possibilities _and_ gives you a small single-player quest to play. The tutorial takes only one -single in-game command to install as explained [here](Contrib/Tutorial-World-Introduction). +single in-game command to install as explained [here](Howto/Starting/Tutorial-World-Introduction). ## Brief summary of features diff --git a/docs/source/Howto/Starting/Building-Quickstart.md b/docs/source/Howto/Starting/Building-Quickstart.md index 71c61c6c9b..15b699f69b 100644 --- a/docs/source/Howto/Starting/Building-Quickstart.md +++ b/docs/source/Howto/Starting/Building-Quickstart.md @@ -1,26 +1,55 @@ -# Building Quickstart +# Using the game and building stuff +[prev lesson](Starting-Part1) | [next lesson](Tutorial-World-Introduction) -The [default command](../../Component/Default-Command-Help) definitions coming with Evennia -follows a style [similar](../../Concept/Using-MUX-as-a-Standard) to that of MUX, so the -commands should be familiar if you used any such code bases before. +In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with +[~90 default commands](Default-Command-Help), and while you can override those as you please, +they can be quite useful. -> Throughout the larger documentation you may come across commands prefixed -> with `@`. This is just an optional marker used in some places to make a -> command stand out. Evennia defaults to ignoring the use of `@` in front of -> your command (so entering `dig` is the same as entering `@dig`). +Connect and log into your new game and you will end up in the "Limbo" location. This +is the only room in the game at this point. Let's explore the commands a little. -The default commands have the following style (where `[...]` marks optional parts): +The default commands has syntax [similar to MUX](../../Concept/Using-MUX-as-a-Standard): command[/switch/switch...] [arguments ...] -A _switch_ is a special, optional flag to the command to make it behave differently. It is always +An example would be + + create/drop box + +A _/switch_ is a special, optional flag to the command to make it behave differently. It is always put directly after the command name, and begins with a forward slash (`/`). The _arguments_ are one or more inputs to the commands. It's common to use an equal sign (`=`) when assigning something to an object. -Below are some examples of commands you can try when logged in to the game. Use `help ` for -learning more about each command and their detailed options. +> Are you used to commands starting with @, like @create? That will work too. Evennia simply ignores +> the preceeding @. + +## Getting help + + help + +Will give you a list of all commands available to you. Use + + help + +to see the in-game help for that command. + +## Looking around + +The most common comman is + + look + +This will show you the description of the current location. `l` is an alias. + +When targeting objects in commands you have two special labels you can use, `here` for the current +room or `me`/`self` to point back to yourself. So + + look me + +will give you your own description. `look here` is, in this case, the same as plain `look`. + ## Stepping Down From Godhood @@ -36,7 +65,11 @@ To temporarily step down from your superuser position you can use the `quell` co This will make you start using the permission of your current character's level instead of your superuser level. If you didn't change any settings your game Character should have an _Developer_ level permission - high as can be without bypassing locks like the superuser does. This will work -fine for the examples on this page. Use `unquell` to get back to superuser status again afterwards. +fine for the examples on this page. Use + + unquell + +to get superuser status again when you are done. ## Creating an Object @@ -109,8 +142,8 @@ Examine will return the value of attributes, including color codes. `examine her the raw description of your current room (including color codes), so that you can copy-and-paste to set its description to something else. -You create new Commands (or modify existing ones) in Python outside the game. See the [Adding -Commands tutorial](Adding-Command-Tutorial) for help with creating your first own Command. +You create new Commands (or modify existing ones) in Python outside the game. We will get to that +later, in the [Commands tutorial](Adding-Command-Tutorial). ## Get a Personality @@ -121,9 +154,15 @@ that is called `BodyFunctions`. To add this to us we will use the `script` comma script self = tutorial_examples.bodyfunctions.BodyFunctions -(note that you don't have to give the full path as long as you are pointing to a place inside the -`contrib` directory, it's one of the places Evennia looks for Scripts). Wait a while and you will -notice yourself starting making random observations. +This string will tell Evennia to dig up the Python code at the place we indicate. It already knows +to look in the `contrib/` folder, so we don't have to give the full path. + +> Note also how we use `.` instead of `/` (or `\` on Windows). This is a so-called "Python path". In a Python-path, +> you separate the parts of the path with `.` and skip the `.py` file-ending. Importantly, it also allows you to point to +Python code _inside_ files, like the `BodyFunctions` class inside `bodyfunctions.py` (we'll get to classes later). +These "Python-paths" are used extensively throughout Evennia. + +Wait a while and you will notice yourself starting making random observations ... script self @@ -141,8 +180,8 @@ the Python path to your script file. The [Scripts](../../Component/Scripts) page ## Pushing Your Buttons -If we get back to the box we made, there is only so much fun you can do with it at this point. It's -just a dumb generic object. If you renamed it to `stone` and changed its description noone would be +If we get back to the box we made, there is only so much fun you can have with it at this point. It's +just a dumb generic object. If you renamed it to `stone` and changed its description, noone would be the wiser. However, with the combined use of custom [Typeclasses](../../Component/Typeclasses), [Scripts](../../Component/Scripts) and object-based [Commands](../../Component/Commands), you could expand it and other items to be as unique, complex and interactive as you want. @@ -150,22 +189,29 @@ and interactive as you want. Let's take an example. So far we have only created objects that use the default object typeclass named simply `Object`. Let's create an object that is a little more interesting. Under `evennia/contrib/tutorial_examples` there is a module `red_button.py`. It contains the enigmatic -`RedButton` typeclass. +`RedButton` class. Let's make us one of _those_! create/drop button:tutorial_examples.red_button.RedButton -We import the RedButton python class the same way you would import it in Python except Evennia makes -sure to look in`evennia/contrib/` so you don't have to write the full path every time. There you go -- one red button. +The same way we did with the Script Earler, we specify a "Python-path" to the Python code we want Evennia +to use for creating the object. There you go - one red button. The RedButton is an example object intended to show off a few of Evennia's features. You will find -that the [Typeclass](../../Component/Typeclasses) and [Commands](../../Component/Commands) controlling it are inside -`evennia/contrib/tutorial_examples/`. +that the [Typeclass](../../Component/Typeclasses) and [Commands](../../Component/Commands) controlling it are +inside [evennia/contrib/tutorial_examples](api:evennia.contrib.tutorial_examples) -If you wait for a while (make sure you dropped it!) the button will blink invitingly. Why don't you -try to push it ...? Surely a big red button is meant to be pushed. You know you want to. +If you wait for a while (make sure you dropped it!) the button will blink invitingly. + +Why don't you try to push it ...? + +Surely a big red button is meant to be pushed. + +You know you want to. + +```warning:: Don't press the invitingly blinking red button. +``` ## Making Yourself a House @@ -189,16 +235,14 @@ also up/down and in/out). It's called `tunnel`: This will create a new room "cliff" with an exit "southwest" leading there and a path "northeast" leading back from the cliff to your current location. -You can create new exits from where you are using the `open` command: +You can create new exits from where you are, using the `open` command: open north;n = house This opens an exit `north` (with an alias `n`) to the previously created room `house`. If you have many rooms named `house` you will get a list of matches and have to select which one you -want to link to. You can also give its database (#dbref) number, which is unique to every object. -This can be found with the `examine` command or by looking at the latest constructions with -`objects`. +want to link to. Follow the north exit to your 'house' or `teleport` to it: @@ -212,63 +256,54 @@ To manually open an exit back to Limbo (if you didn't do so with the `dig` comma open door = limbo -(or give limbo's dbref which is #2) +(You can also us the #dbref of limbo, which you can find by using `examine here` when in limbo). ## Reshuffling the World You can find things using the `find` command. Assuming you are back at `Limbo`, let's teleport the -_large box to our house_. +_large box_ to our house. - > teleport box = house - very large box is leaving Limbo, heading for house. - Teleported very large box -> house. + teleport box = house + very large box is leaving Limbo, heading for house. + Teleported very large box -> house. We can still find the box by using find: - > find box - One Match(#1-#8): - very large box(#8) - src.objects.objects.Object + find box + One Match(#1-#8): + very large box(#8) - src.objects.objects.Object Knowing the `#dbref` of the box (#8 in this example), you can grab the box and get it back here without actually yourself going to `house` first: teleport #8 = here -(You can usually use `here` to refer to your current location. To refer to yourself you can use -`self` or `me`). The box should now be back in Limbo with you. +As mentioned, `here` is an alias for 'your current location'. The box should now be back in Limbo with you. We are getting tired of the box. Let's destroy it. destroy box -You can destroy many objects in one go by giving a comma-separated list of objects (or their -#dbrefs, if they are not in the same location) to the command. +It will ask you for confirmation. Once you give it, the box will be gone. + +You can destroy many objects in one go by giving a comma-separated list of objects (or a range +of #dbrefs, if they are not in the same location) to the command. ## Adding a Help Entry -An important part of building is keeping the help files updated. You can add, delete and append to -existing help entries using the `sethelp` command. +The Command-help is something you modify in Python code. We'll get to that when we get to how to +add Commands. But you can also add regular help entries, for example to explain something about +the history of your game world: + + sethelp/add History = At the dawn of time ... + +Next we will take a little detour to look at the _Tutorial World_. This is a little solo adventure +that comes with Evennia, a showcase for some of the things that are possible. - sethelp/add MyTopic = This help topic is about ... ## Adding a World After this brief introduction to building you may be ready to see a more fleshed-out example. -Evennia comes with a tutorial world for you to explore. +Evennia comes with a tutorial world for you to explore. We will try that out in the next section. -First you need to switch back to _superuser_ by using the `unquell` command. Next, place yourself in -`Limbo` and run the following command: - - batchcommand tutorial_world.build - -This will take a while (be patient and don't re-run the command). You will see all the commands used -to build the world scroll by as the world is built for you. - -You will end up with a new exit from Limbo named _tutorial_. Apart from being a little solo- -adventure in its own right, the tutorial world is a good source for learning Evennia building (and -coding). - -Read [the batch -file](https://github.com/evennia/evennia/blob/master/evennia/contrib/tutorial_world/build.ev) to see -exactly how it's built, step by step. See also more info about the tutorial world [here](Tutorial- -World-Introduction). \ No newline at end of file +[prev lesson](Starting-Part1) | [next lesson](Tutorial-World-Introduction) diff --git a/docs/source/Howto/Starting/Starting-Part1.md b/docs/source/Howto/Starting/Starting-Part1.md index 9d5d7708dc..b3bc6aca1e 100644 --- a/docs/source/Howto/Starting/Starting-Part1.md +++ b/docs/source/Howto/Starting/Starting-Part1.md @@ -1,18 +1,102 @@ # Evennia Starting Tutorial + [Next lesson](Building-Quickstart) + This is a multi-part Tutorial that will gradually take you from first installation to making your own first little game in Evennia. Let's get started! ```sidebar:: Parts of the Starting tutorial - **Part 1**: What we have: + **Part 1**: What we have A tour of Evennia and how to use the tools, including an introduction to Python. - [Part 2: What we want](Starting-Part2): + Part 2: `What we want `_ Planning our tutorial game and what to think about when planning your own in the future. - [Part 3: How we get there](Starting-Part3): + Part 3: `How we get there `_ Getting down to the meat of extending Evennia to make our game - [Part 4: Using what we created](Starting-Part4): + Part 4: `Using what we created `_ Building a tech-demo and world content to go with our code - [Part 5: Showing the world](Starting-Part5): + Part 5: `Showing the world `_ Taking our new game online and let players try it out ``` + +## Lessons of Part 1 - "What we have" + +1. Introduction & Overview (you are here) +1. [Building stuff](Building-Quickstart) +1. [The Tutorial World](Tutorial-World-Introduction) +1. [Python basics](Python-basic-introduction) +1. [Python classes](Python-basic-tutorial-part-two) +1. [Running Python in- and outside the game](Execute-Python-Code) +1. [Understanding errors](Understanding-Errors) +1. [Searching for things](Tutorial-Searching-For-Objects) +1. [A walkthrough of the API](Walkthrough-of-API) + +In this first part we'll focus on what we get out of the box in Evennia - we'll get used to the tools, +where things are and how we find things we are looking for. We will also dive into some of things you'll +need to know to fully utilize the system, including giving a brief rundown of Python concepts. + +## Things you will need + +### A Command line + +First of all, you need to know how to find your Terminal/Console in your OS. The Evennia server can be controlled +from in-game, but you _will_ need to use the command-line to get anywhere. Here are some starters: + +- [Django-girls' Intro to the Command line for different OS:es](https://tutorial.djangogirls.org/en/intro_to_command_line/) + +### A MUD client + +You might already have a MUD-client you prefer. Check out the [grid of supported clients](../../Setup/Client-Support-Grid) for aid. +If telnet's not your thing, you can also just use Evennia's web client in your browser. + +> In this documentation we often use 'MUD' and 'MU' or 'MU*' interchangeably + as labels to represent all the historically different forms of text-based multiplayer game-styles, + like MUD, MUX, MUSH, MUCK, MOO and others. Evennia can be used to create all those game-styles + and more. + +### An Editor +You need a text-editor to edit Python source files. Most everything that can edit and output raw +text works (so not Word). + +- [Here's a blog post summing up some of the alternatives](https://www.elegantthemes.com/blog/resources/best-code-editors) - these +things don't change much from year to year. Popular choices for Python are PyCharm, VSCode, Atom, Sublime Text and Notepad++. + Evennia is to a very large degree coded in VIM, but that's not suitable for beginners. + +> Hint: When setting up your editor, make sure that pressing TAB inserts _4 spaces_ rather than a Tab-character. Since +> Python is whitespace-aware, this will make your life a lot easier. + + +### Set up a game dir for the tutorial + +Next you should make sure you have [installed Evennia](../../Setup/Setup-Quickstart). If you followed the instructions +you will already have created a game-dir. You could use that for this tutorial or you may want to do the +tutorial in its own, isolated game dir; it's up to you. + +- If you want a new gamedir for the tutorial game and already have Evennia running with another gamedir, +first enter that gamedir and run + + evennia stop + +> If you want to run two parallel servers, that'd be fine too, but one would have to use +> different ports from the defaults, or there'd be a clash. We will go into changing settings later. +- Now go to where you want to create your tutorial-game. We will always refer to it as `mygame` so + it may be convenient if you do too: + + evennia --init mygame + cd mygame + evennia migrate + evennia start --log + + Add your superuser name and password at the prompt (email is optional). Make sure you can + go to `localhost:4000` in your MUD client or to [http://localhost:4001](http://localhost:4001) + in your web browser (Mac users: Try `127.0.0.1` instead of `localhost` if you have trouble). + + The above `--log` flag will have Evennia output all its logs to the terminal. This will block + the terminal from other input. To leave the log-view, press `Ctrl-C` (`Cmd-C` on Mac). To see + the log again just run + + evennia --log + + You should now be good to go! + + [Next lesson](Building-Quickstart) diff --git a/docs/source/Howto/Starting/Tutorial-World-Introduction.md b/docs/source/Howto/Starting/Tutorial-World-Introduction.md new file mode 100644 index 0000000000..5cda418dbd --- /dev/null +++ b/docs/source/Howto/Starting/Tutorial-World-Introduction.md @@ -0,0 +1,119 @@ +# The Tutorial World + +[prev lesson](Building-Quickstart) | [next lesson]() + +The *Tutorial World* is a small and functioning MUD-style game world shipped with Evennia. +It's a small showcase of what is possible. It can also be useful for those who have an easier +time learning by deconstructing existing code. + +Stand in the Limbo room and install it with + + batchcommand tutorial_world.build + +What this does is to run the build script +[evennia/contrib/tutorial_world/build.ev](github:evennia/contrib/tutorial_world/build.ev). +This is pretty much just a list of build-commands executed in sequence by the `batchcommand` command. +Wait for the building to complete and don't run it twice. A new exit should have appeared named _Tutorial_. + +The game consists of a single-player quest and has some 20 rooms that you can explore as you seek +to discover the whereabouts of a mythical weapon. Make sure you don't play as superuser: + + quell + +Enter the new exit by writing `tutorial`. Enjoy! If you succeed you will eventually +end up back in Limbo. + +## Gameplay + +![the castle off the moor](https://images-wixmp-ed30a86b8c4ca887773594c2.wixmp.com/f/22916c25-6299-453d-a221-446ec839f567/da2pmzu-46d63c6d-9cdc-41dd-87d6-1106db5a5e1a.jpg/v1/fill/w_600,h_849,q_75,strp/the_castle_off_the_moor_by_griatch_art_da2pmzu-fullview.jpg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOiIsImlzcyI6InVybjphcHA6Iiwib2JqIjpbW3siaGVpZ2h0IjoiPD04NDkiLCJwYXRoIjoiXC9mXC8yMjkxNmMyNS02Mjk5LTQ1M2QtYTIyMS00NDZlYzgzOWY1NjdcL2RhMnBtenUtNDZkNjNjNmQtOWNkYy00MWRkLTg3ZDYtMTEwNmRiNWE1ZTFhLmpwZyIsIndpZHRoIjoiPD02MDAifV1dLCJhdWQiOlsidXJuOnNlcnZpY2U6aW1hZ2Uub3BlcmF0aW9ucyJdfQ.omuS3D1RmFiZCy9OSXiIita-HxVGrBok3_7asq0rflw) + +*To get into the mood of this miniature quest, imagine you are an adventurer out to find fame and +fortune. You have heard rumours of an old castle ruin by the coast. In its depth a warrior princess +was buried together with her powerful magical weapon - a valuable prize, if it's true. Of course +this is a chance to adventure that you cannot turn down!* + +*You reach the ocean in the midst of a raging thunderstorm. With wind and rain screaming in your +face you stand where the moor meets the sea along a high, rocky coast ...* + +--- +### Hints: + +- Look at everything. While a demo, this is not necessarily trivial, depending on your experience with +text-based adventure games. Just remember that everything can be solved or bypassed. +- Some things cannot be damaged by mortal weapons. In that case it's OK to run away. Expect + to be chased though. +- Some objects are interactive in more than one way. Use the normal `help` command to get a feel for +which commands are available at any given time. +- Use the command `tutorial` to get insight behind the scenes of the game. +- In order to fight, you need to first find some type of weapon. + - *slash* is a normal attack + - *stab* launches an attack that makes more damage but has a lower chance to hit. + - *defend* will lower the chance to taking damage on your enemy's next attack. +- Being defeated is a part of the experience. You can't actually die, but getting knocked out + means being left in the dark ... + +## Once you are done (or had enough) + +Afterwards you'll either have conquered the old ruin and returned in glory and triumph ... or +you returned limping and whimpering from the challenge through `telport limbo`. +Either way you should now be back in Limbo, able to reflect on the experience. + +Some features exemplified by the tutorial world: + +- Rooms with custom ability to show details (like looking at the wall in the dark room) +- Hidden or impassable exits until you fulfilled some criterion +- Objects with multiple custom interactions (like swords, the well, the obelisk ...) +- Large-area rooms (that bridge is actually only one room!) +- Outdoor weather rooms with weather (the rain pummeling you) +- Dark room, needing light source to reveal itself (the burning splinter even burns out after a while) +- Puzzle object (the wines in the dark cell; hope you didn't get stuck!) +- Multi-room puzzle (the obelisk and the crypt) +- Aggressive mobile with roam, pursue and battle state-engine AI (quite deadly until you find the right weapon) +- Weapons, also used by mobs (most are admittedly not that useful against the big baddie) +- Simple combat system with attack/defend commands (teleporting on-defeat) +- Object spawning (the weapons in the barrel and the final weapoon is actually randomized) +- Teleporter trap rooms (if you fail the obelisk puzzle) + +```sidebar:: Extra Credit + + If you have previous programming experience (or after you have gone + through this Starter tutorial) it may be instructive to dig a little deeper into the Tutorial-world + code to learn how it achieves what it does. The code is heavily documented. + You can find all the code in `evennia/contrib/tutorial_world <../../api/evennia.contrib.tutorial_world.html>`_, + the build-script is `here `_. + + + When reading and learning from the code, however, keep in mind that *Tutorial World* was created with a very + specific goal in mind: to install easily and to not permanently modify the rest of the server. It therefore + goes to some length to use only temporary solutions and to clean up after itself. This is not something + you will usually need to worry about when making your own game. +``` + +Quite a lot of stuff crammed in such a small area! + +## Uninstall the tutorial world + +Once are done playing with the tutorial world, let's uninstall it. +Uninstalling the tutorial world basically means deleting all the rooms and objects it consists of. +Make sure you are back in Limbo, then + + find tut#01 + find tut#16 + +This should locate the first and last rooms created by `build.ev` - *Intro* and *Outro*. If you +installed normally, everything created between these two numbers should be part of the tutorial. +Note their #dbref numbers, for example 5 and 80. Next we just delete all objects in that range: + + del 5-80 + +You will see some errors since some objects are auto-deleted and so cannot be found when the delete +mechanism gets to them. That's fine. You should have removed the tutorial completely once the +command finishes. + +Even if the game-style of the Tutorial-world was not similar to the one you are interested in, it +should hopefully have given you a little taste of some of the possibilities of Evennia. Now we'll +move on with how to access this power through code. + + +[prev lesson](Building-Quickstart) | [next lesson]() + diff --git a/docs/source/Howto/Starting/Tutorial-for-basic-MUSH-like-game.md b/docs/source/Howto/Starting/Tutorial-for-basic-MUSH-like-game.md index 2b3b226eaf..361e84dcf6 100644 --- a/docs/source/Howto/Starting/Tutorial-for-basic-MUSH-like-game.md +++ b/docs/source/Howto/Starting/Tutorial-for-basic-MUSH-like-game.md @@ -649,6 +649,6 @@ The simple "Power" game mechanic should be easily expandable to something more f useful, same is true for the combat score principle. The `+attack` could be made to target a specific player (or npc) and automatically compare their relevant attributes to determine a result. -To continue from here, you can take a look at the [Tutorial World](../../Contrib/Tutorial-World-Introduction). For +To continue from here, you can take a look at the [Tutorial World](Tutorial-World-Introduction). For more specific ideas, see the [other tutorials and hints](Tutorials) as well as the [Developer Central](Developer-Central). \ No newline at end of file diff --git a/docs/source/Setup/Extended-Installation.md b/docs/source/Setup/Extended-Installation.md index 5663ff6830..7ce36f5cc8 100644 --- a/docs/source/Setup/Extended-Installation.md +++ b/docs/source/Setup/Extended-Installation.md @@ -438,7 +438,7 @@ logged in, stand in the `Limbo` room and run @batchcommand tutorial_world.build -to build [Evennia's tutorial world](../Contrib/Tutorial-World-Introduction) - it's a small solo quest to +to build [Evennia's tutorial world](../Howto/Starting/Tutorial-World-Introduction) - it's a small solo quest to explore. Only run the instructed `@batchcommand` once. You'll get a lot of text scrolling by as the tutorial is built. Once done, the `tutorial` exit will have appeared out of Limbo - just write `tutorial` to enter it. diff --git a/docs/source/_static/nature.css b/docs/source/_static/nature.css index 8c2c57e5a0..75eaeb0111 100644 --- a/docs/source/_static/nature.css +++ b/docs/source/_static/nature.css @@ -217,8 +217,8 @@ div.admonition p.admonition-title + p { display: inline; } -div.highlight{ - background-color: white; +div.highlight { + background-color: #f1f1ef; } div.note { diff --git a/docs/source/toc.md b/docs/source/toc.md index dab1260f5b..0496c537ff 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -68,7 +68,6 @@ - [Contrib/Dialogues in events](Contrib/Dialogues-in-events) - [Contrib/Dynamic In Game Map](Contrib/Dynamic-In-Game-Map) - [Contrib/Static In Game Map](Contrib/Static-In-Game-Map) -- [Contrib/Tutorial World Introduction](Contrib/Tutorial-World-Introduction) - [Contributing](Contributing) - [Contributing Docs](Contributing-Docs) - [Evennia API](Evennia-API) @@ -112,6 +111,7 @@ - [Howto/Starting/Starting Part5](Howto/Starting/Starting-Part5) - [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 World Introduction](Howto/Starting/Tutorial-World-Introduction) - [Howto/Starting/Tutorial for basic MUSH like game](Howto/Starting/Tutorial-for-basic-MUSH-like-game) - [Howto/Starting/Web Tutorial](Howto/Starting/Web-Tutorial) - [Howto/Tutorial Aggressive NPCs](Howto/Tutorial-Aggressive-NPCs)