Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-29 03:57:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Refactor 1.0 docs with new toctree structure and inheritance

Browse source
This commit is contained in:
Griatch 2022-02-06 19:27:15 +01:00
parent 62477eac50
commit 628afe9367
142 changed files with 3967 additions and 3024 deletions
Download patch file Download diff file Expand all files Collapse all files

46
docs/source/Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Part2-Intro.md Normal file
View file

@ -0,0 +1,46 @@
# Part 2: What we want
```{eval-rst}
.. sidebar:: Beginner Tutorial Parts
`Introduction <../Beginner-Tutorial-Intro.html>`_
Getting set up.
Part 1: `What we have <../Part1/Beginner-Tutorial-Part1-Intro.html>`_
A tour of Evennia and how to use the tools, including an introduction to Python.
**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 <../Part3/Beginner-Tutorial-Part3-Intro.html>`_
Getting down to the meat of extending Evennia to make our game
Part 4: `Using what we created <../Part4/Beginner-Tutorial-Part4-Intro.html>`_
Building a tech-demo and world content to go with our code
Part 5: `Showing the world <../Part5/Beginner-Tutorial-Part5-Intro.html>`_
Taking our new game online and let players try it out
```
In Part two of the Beginner Tutorial we'll take a step back and plan out the kind of tutorial
game we want to make. This is a more 'theoretical' part where we won't do any hands-on
programming.
In the process we'll go through the common questions of "where to start"
and "what to think about" when creating a multiplayer online text game.
## Lessons
```{toctree}
:maxdepth: 1
Planning-Where-Do-I-Begin.md
Game-Planning.md
Planning-Some-Useful-Contribs.md
Planning-The-Tutorial-Game.md
```
## Table of Contents
```{toctree}
Planning-Where-Do-I-Begin.md
Game-Planning.md
Planning-Some-Useful-Contribs.md
Planning-The-Tutorial-Game.md
```

209
docs/source/Howtos/Beginner-Tutorial/Part2/Game-Planning.md Normal file
View file

@ -0,0 +1,209 @@
# On Planning a Game
Last lesson we asked ourselves some questions about our motivation. In this one we'll present
some more technical questions to consider. In the next lesson we'll answer them for the sake of
our tutorial game.
Note that the suggestions on this page are just that - suggestions. Also, they are primarily aimed at a lone
hobby designer or a small team developing a game in their free time.
```{important}
Your first all overshadowing goal is to beat the odds and get **something** out the door!
Even if it's a scaled-down version of your dream game, lacking many "must-have" features!
```
Remember: *99.99999% of all great game ideas never lead to a game*. Especially not to an online
game that people can actually play and enjoy. It's better to get your game out there and expand on it
later than to code in isolation until you burn out, lose interest or your hard drive crashes.
- Keep the scope of your initial release down. Way down.
- Start small, with an eye towards expansions later, after first release.
- If the suggestions here seems boring or a chore to you, do it your way instead. Everyone's different.
- Keep having _fun_. You must keep your motivation up, whichever way works for _you_.
## The steps
Here are the rough steps towards your goal.
1. Planning
2. Coding + Gradually building a tech-demo
3. Building the actual game world
4. Release
5. Celebrate
## Planning
You need to have at least a rough idea about what you want to create. Some like a lot of planning, others
do it more seat-of-the-pants style. Regardless, while _some_ planning is always good to do, it's common
to have your plans change on you as you create your code prototypes. So don't get _too_ bogged down in
the details out of the gate.
Many prospective game developers are very good at *parts* of this process, namely in defining what their
world is "about": The theme, the world concept, cool monsters and so on. Such things are very important. But
unfortunately, they are not enough to make your game. You need to figure out how to accomplish your ideas in
Evennia.
Below are some questions to get you going. In the next lesson we will try to answer them for our particular
tutorial game. There are of course many more questions you could be asking yourself.
### Administration
- Should your game rules be enforced by coded systems or by human game masters?
- What is the staff hierarchy in your game? Is vanilla Evennia roles enough or do you need something else?
- Should players be able to post out-of-characters on channels and via other means like bulletin-boards?
### Building
- How will the world be built? Traditionally (from in-game with build-commands) or externally (by batchcmds/code
or directly with custom code)?
- Can only privileged Builders create things or should regular players also have limited build-capability?
### Systems
- Do you base your game off an existing RPG system or make up your own?
- What are the game mechanics? How do you decide if an action succeeds or fails?
- Does the flow of time matter in your game - does night and day change? What about seasons?
- Do you want changing, global weather or should weather just be set manually in roleplay?
- Do you want a coded world-economy or just a simple barter system? Or no formal economy at all?
- Do you have concepts like reputation and influence?
- Will your characters be known by their name or only by their physical appearance?
### Rooms
- Is a simple room description enough or should the description be able to change (such as with time, by
light conditions, weather or season)?
- Should the room have different statuses? Can it have smells, sounds? Can it be affected by
dramatic weather, fire or magical effects? If so, how would this affect things in the room? Or are
these things something admins/game masters should handle manually?
- Can objects be hidden in the room? Can a person hide in the room? How does the room display this?
### Objects / items
- How numerous are your objects? Do you want large loot-lists or are objects just role playing props
created on demand?
- If you use money, is each coin a separate object or do you just store a bank account value?
- Do multiple similar objects form stacks and how are those stacks handled in that case?
- Does an object have weight or volume (so you cannot carry an infinite amount of them)?
- Can objects be broken? Can they be repaired?
- Can you fight with a chair or a flower or must you use a specific 'weapon' kind of thing?
- Will characters be able to craft new objects?
- Should mobs/NPCs have some sort of AI?
- Are NPCs and mobs different entities? How do they differ?
- Should there be NPCs giving quests? If so, how do you track Quest status?
### Characters
- Can players have more than one Character active at a time or are they allowed to multi-play?
- How does the character-generation work? Walk from room-to-room? A menu?
- How do you implement different "classes" or "races"? Are they separate types of objects or do you
simply load different stats on a basic object depending on what the Player wants?
- If a Character can hide in a room, what skill will decide if they are detected?
- What does the skill tree look like? Can a Character gain experience to improve? By killing
enemies? Solving quests? By roleplaying?
- May player-characters attack each other (PvP)?
- What are the penalties of defeat? Permanent death? Quick respawn? Time in prison?
A MUD's a lot more involved than you would think and these things hang together in a complex web. It
can easily become overwhelming and it's tempting to want *all* functionality right out of the door.
Try to identify the basic things that "make" your game and focus *only* on them for your first
release. Make a list. Keep future expansions in mind but limit yourself.
## Coding and Tech demo
This is the actual work of creating the "game" part of your game. As you code and test systems you should
build a little "tech demo" along the way.
```{sidebar} Tech demo
With "tech demo" we mean a small example of your code in-action: A room with a mob,
a way to jump into and test character-creation etc. The tech demo need not be pretty, it's
there to test functionality. It's not the beginning of your game world (unless you find that
to be more fun).
```
Try to avoid going wild with building a huge game world before you have a tech-demo showing off all parts
you expect to have in the first version of your game. Otherwise you run the risk of having to redo it all
again.
Evennia tries hard to make the coding easier for you, but there is no way around the fact that if you want
anything but a basic chat room you *will* have to bite the bullet and code your game (or find a coder willing
to do it for you).
> Even if you won't code anything yourself, as a designer you need to at least understand the basic
paradigms and components of Evennia. It's recommended you look over the rest of this Beginner Tutorial to learn
what tools you have available.
During Coding you look back at the things you wanted during the **Planning** phase and try to
implement them. Don't be shy to update your plans if you find things easier/harder than you thought.
The earlier you revise problems, the easier they will be to fix.
A good idea is to host your code online using _version control_. Github.com offers free Private repos
these days if you don't want the world to learn your secrets. Not only version control
make it easy for your team to collaborate, it also means
your work is backed up at all times. The page on [Version Control](../../../Coding/Version-Control.md)
will help you to setting up a sane developer environment with proper version control.
## World Building
Up until this point we've only had a few tech-demo objects in the database. This step is the act of
populating the database with a larger, thematic world. Too many would-be developers jump to this
stage too soon (skipping the **Coding** or even **Planning** stages). What if the rooms you build
now doesn't include all the nice weather messages the code grows to support? Or the way you store
data changes under the hood? Your building work would at best require some rework and at worst you
would have to redo the whole thing. You could be in for a *lot* of unnecessary work if you build stuff
en masse without having the underlying code systems in some reasonable shape first.
So before starting to build, the "game" bit (**Coding** + **Testing**) should be more or less
**complete**, *at least to the level of your initial release*.
Make sure it is clear to yourself and your eventual builders just which parts of the world you want
for your initial release. Establish for everyone which style, quality and level of detail you expect.
Your goal should *not* be to complete your entire world in one go. You want just enough to make the
game's "feel" come across. You want a minimal but functioning world where the intended game play can
be tested and roughly balanced. You can always add new areas later.
During building you get free and extensive testing of whatever custom build commands and systems you
have made at this point. If Builders and coders are different people you also
get a chance to hear if some things are hard to understand or non-intuitive. Make sure to respond
to this feedback.
## Alpha Release
As mentioned, don't hold onto your world more than necessary. *Get it out there* with a huge *Alpha*
flag and let people try it!
Call upon your alpha-players to try everything - they *will* find ways 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.md) 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)!
## Beta Release/Perpetual Beta
Once things stabilize in Alpha you can move to *Beta* and let more people in. Many MUDs are in
[perpetual beta](https://en.wikipedia.org/wiki/Perpetual_beta), meaning they are never considered
"finished", but just repeat the cycle of Planning, Coding, Testing and Building over and over as new
features get implemented or Players come with suggestions. As the game designer it is now up to you
to gradually perfect your vision.
## Congratulate yourself!
You are worthy of a celebration since at this point you have joined the small, exclusive crowd who
have made their dream game a reality!
## Planning our tutorial game
In the next lesson we'll make use of these general points and try to plan out our tutorial game.

244
docs/source/Howtos/Beginner-Tutorial/Part2/Planning-Some-Useful-Contribs.md Normal file
View file

@ -0,0 +1,244 @@
# Planning the use of some useful contribs
Evennia is deliberately bare-bones out of the box. The idea is that you should be as unrestricted as possible
in designing your game. This is why you can easily replace the few defaults we have and why we don't try to
prescribe any major game systems on you.
That said, Evennia _does_ offer some more game-opinionated _optional_ stuff. These are referred to as _Contribs_
and is an ever-growing treasure trove of code snippets, concepts and even full systems you can pick and choose
from to use, tweak or take inspiration from when you make your game.
The [Contrib overview](../../../Contribs/Contribs-Overview.md) page gives the full list of the current roster of contributions. On
this page we will review a few contribs we will make use of for our game. We will do the actual installation
of them when we start coding in the next part of this tutorial series. While we will introduce them here, you
are wise to read their doc-strings yourself for the details.
This is the things we know we need:
- A barter system
- Character generation
- Some concept of wearing armor
- The ability to roll dice
- Rooms with awareness of day, night and season
- Roleplaying with short-descs, poses and emotes
- Quests
- Combat (with players and against monsters)
## Barter contrib
[source](../../../api/evennia.contrib.game_systems.barter.md)
Reviewing this contrib suggests that it allows for safe trading between two parties. The basic principle
is that the parties puts up the stuff they want to sell and the system will guarantee that these systems are
exactly what is being offered. Both sides can modify their offers (bartering) until both mark themselves happy
with the deal. Only then the deal is sealed and the objects are exchanged automatically. Interestingly, this
works just fine for money too - just put coin objects on one side of the transaction.
Sue > trade Tom: Hi, I have a necklace to sell; wanna trade for a healing potion?
Tom > trade Sue: Hm, I could use a necklace ...
<both accepted trade. Start trade>
Sue > offer necklace: This necklace is really worth it.
Tom > evaluate necklace:
<Tom sees necklace stats>
Tom > offer ration: I don't have a healing potion, but I'll trade you an iron ration!
Sue > Hey, this is a nice necklace, I need more than a ration for it...
Tom > offer ration, 10gold: Ok, a ration and 10 gold as well.
Sue > accept: Ok, that sounds fair!
Tom > accept: Good! Nice doing business with you.
<goods change hands automatically. Trade ends>
Arguably, in a small game you are just fine to just talk to people and use `give` to do the exchange. The
barter system guarantees trading safety if you don't trust your counterpart to try to give you the wrong thing or
to run away with your money.
We will use the barter contrib as an optional feature for player-player bartering. More importantly we can
add it for NPC shopkeepers and expand it with a little AI, which allows them to potentially trade in other
things than boring gold coin.
## Clothing contrib
[source](../../../api/evennia.contrib.game_systems.clothing.md)
This contrib provides a full system primarily aimed at wearing clothes, but it could also work for armor. You wear
an object in a particular location and this will then be reflected in your character's description. You can
also add roleplaying flavor:
> wear helmet slightly askew on her head
look self
Username is wearing a helmet slightly askew on her head.
By default there are no 'body locations' in this contrib, we will need to expand on it a little to make it useful
for things like armor. It's a good contrib to build from though, so that's what we'll do.
## Dice contrib
[source](../../../api/evennia.contrib.rpg.dice.md)
The dice contrib presents a general dice roller to use in game.
> roll 2d6
Roll(s): 2 and 5. Total result is 7.
> roll 1d100 + 2
Roll(s): 43. Total result is 47
> roll 1d20 > 12
Roll(s): 7. Total result is 7. This is a failure (by 5)
> roll/hidden 1d20 > 12
Roll(s): 18. Total result is 17. This is a success (by 6). (not echoed)
The contrib also has a python function for producing these results in-code. However, while
we will emulate rolls for our rule system, we'll do this as simply as possible with Python's `random`
module.
So while this contrib is fun to have around for GMs or for players who want to get a random result
or play a game, we will not need it for the core of our game.
## Extended room contrib
[source](../../../api/evennia.contrib.grid.extended_room.md)
This is a custom Room typeclass that changes its description based on time of day and season.
For example, at night, in wintertime you could show the room as being dark and frost-covered while in daylight
at summer it could describe a flowering meadow. The description can also contain special markers, so
`<morning> ... </morning>` would include text only visible at morning.
The extended room also supports _details_, which are things to "look at" in the room without there having
to be a separate database object created for it. For example, a player in a church may do `look window` and
get a description of the windows without there needing to be an actual `window` object in the room.
Adding all those extra descriptions can be a lot of work, so they are optional; if not given the room works
like a normal room.
The contrib is simple to add and provides a lot of optional flexibility, so we'll add it to our
game, why not!
## RP-System contrib
[source](../../../api/evennia.contrib.rpg.rpsystem.md)
This contrib adds a full roleplaying subsystem to your game. It gives every character a "short-description"
(sdesc) that is what people will see when first meeting them. Let's say Tom has an sdesc "A tall man" and
Sue has the sdesc "A muscular, blonde woman"
Tom > look
Tom: <room desc> ... You see: A muscular, blonde woman
Tom > emote /me smiles to /muscular.
Tom: Tom smiles to A muscular, blonde woman.
Sue: A tall man smiles to Sue.
Tom > emote Leaning forward, /me says, "Well hello, what's yer name?"
Tom: Leaning forward, Tom says, "Well hello..."
Sue: Leaning forward, A tall man says, "Well hello, what's yer name?"
Sue > emote /me grins. "I'm Angelica", she says.
Sue: Sue grins. "I'm Angelica", she says.
Tom: A muscular, blonde woman grins. "I'm Angelica", she says.
Tom > recog muscular Angelica
Tom > emote /me nods to /angelica: "I have a message for you ..."
Tom: Tom nods to Angelica: "I have a message for you ..."
Sue: A tall man nods to Sue: "I have a message for you ..."
Above, Sue introduces herself as "Angelica" and Tom uses this info to `recoc` her as "Angelica" hereafter. He
could have `recoc`-ed her with whatever name he liked - it's only for his own benefit. There is no separate
`say`, the spoken words are embedded in the emotes in quotes `"..."`.
The RPSystem module also includes options for `poses`, which help to establish your position in the room
when others look at you.
Tom > pose stands by the bar, looking bored.
Sue > look
Sue: <room desc> ... A tall man stands by the bar, looking bored.
You can also wear a mask to hide your identity; your sdesc will then be changed to the sdesc of the mask,
like `a person with a mask`.
The RPSystem gives a lot of roleplaying power out of the box, so we will add it. There is also a separate
[rplanguage](../../../api/evennia.contrib.rpg.rpsystem.md) module that integrates with the spoken words in your emotes and garbles them if you don't understand
the language spoken. In order to restrict the scope we will not include languages for the tutorial game.
## Talking NPC contrib
[source](../../../api/evennia.contrib.tutorials.talking_npc.md)
This exemplifies an NPC with a menu-driven dialogue tree. We will not use this contrib explicitly, but it's
good as inspiration for how we'll do quest-givers later.
## Traits contrib
[source](../../../api/evennia.contrib.rpg.traits.md)
An issue with dealing with roleplaying attributes like strength, dexterity, or skills like hunting, sword etc
is how to keep track of the values in the moment. Your strength may temporarily be buffed by a strength-potion.
Your swordmanship may be worse because you are encumbered. And when you drink your health potion you must make
sure that those +20 health does not bring your health higher than its maximum. All this adds complexity.
The _Traits_ contrib consists of several types of objects to help track and manage values like this. When
installed, the traits are accessed on a new handler `.traits`, for example
> py self.traits.hp.value
100
> py self.traits.hp -= 20 # getting hurt
> py self.traits.hp.value
80
> py self.traits.hp.reset() # drink a potion
> py self.traits.hp.value
100
A Trait is persistent (it uses an Attribute under the hood) and tracks changes, min/max and other things
automatically. They can also be added together in various mathematical operations.
The contrib introduces three main Trait-classes
- _Static_ traits for single values like str, dex, things that at most gets a modifier.
- _Counters_ is a value that never moves outside a given range, even with modifiers. For example a skill
that can at most get a maximum amount of buff. Counters can also easily be _timed_ so that they decrease
or increase with a certain rate per second. This could be good for a time-limited curse for example.
- _Gauge_ is like a fuel-gauge; it starts at a max value and then empties gradually. This is perfect for
things like health, stamina and the like. Gauges can also change with a rate, which works well for the
effects of slow poisons and healing both.
```
> py self.traits.hp.value
100
> py self.traits.hp.rate = -1 # poisoned!
> py self.traits.hp.ratetarget = 50 # stop at 50 hp
# Wait 30s
> py self.traits.hp.value
70
# Wait another 30s
> py self.traits.hp.value
50 # stopped at 50
> py self.traits.hp.rate = 0 # no more poison
> py self.traits.hp.rate = 5 # healing magic!
# wait 5s
> pyself.traits.hp.value
75
```
Traits will be very practical to use for our character sheets.
## Turnbattle contrib
[source](../../../api/evennia.contrib.game_systems.turnbattle.md)
This contrib consists of several implementations of a turn-based combat system, divivided into complexity:
- basic - initiative and turn order, attacks against defense values, damage.
- equip - considers weapons and armor, wielding and weapon accuracy.
- items - adds usable items with conditions and status effects
- magic - adds spellcasting system using MP.
- range - adds abstract positioning and 1D movement to differentiate between melee and ranged attacks.
The turnbattle system is comprehensive, but it's meant as a base to start from rather than offer
a complete system. It's also not built with _Traits_ in mind, so we will need to adjust it for that.
## Conclusions
With some contribs selected, we have pieces to build from and don't have to write everything from scratch.
We will need Quests and will likely need to do a bunch of work on Combat to adapt the combat contrib
to our needs.
We will now move into actually starting to implement our tutorial game
in the next part of this tutorial series. When doing this for yourself, remember to refer
back to your planning and adjust it as you learn what works and what does not.

425
docs/source/Howtos/Beginner-Tutorial/Part2/Planning-The-Tutorial-Game.md Normal file
View file

@ -0,0 +1,425 @@
# Planning our tutorial game
Using the general plan from last lesson we'll now establish what kind of game we want to create for this tutorial.
Remembering that we need to keep the scope down, let's establish some parameters.
Note that for your own
game you don't _need_ to agree/adopt any of these. Many game-types need more or much less than this.
But this makes for good, instructive examples.
- To have something to refer to rather than just saying "our tutorial game" over and over, we'll
name it ... _EvAdventure_.
- We want EvAdventure be a small game we can play ourselves for fun, but which could in principle be expanded
to something more later.
- Let's go with a fantasy theme, it's well understood.
- We'll use some existing, simple RPG system.
- We want to be able to create and customize a character of our own.
- We want the tools to roleplay with other players.
- We don't want to have to rely on a Game master to resolve things, but will rely on code for skill resolution
and combat.
- We want monsters to fight and NPCs we can talk to. So some sort of AI.
- We want to be able to buy and sell stuff, both with NPCs and other players.
- We want some sort of crafting system.
- We want some sort of quest system.
Let's answer the questions from the previous lesson and discuss some of the possibilities.
## Administration
### Should your game rules be enforced by coded systems by human game masters?
Generally, the more work you expect human staffers/GMs to do, the less your code needs to work. To
support GMs you'd need to design commands to support GM-specific actions and the type of game-mastering
you want them to do. You may need to expand communication channels so you can easily
talk to groups people in private and split off gaming groups from each other. RPG rules could be as simple
as the GM sitting with the rule books and using a dice-roller for visibility.
GM:ing is work-intensive however, and even the most skilled and enthusiastic GM can't be awake all hours
of the day to serve an international player base. The computer never needs sleep, so having the ability for
players to "self-serve" their RP itch when no GMs are around is a good idea even for the most GM-heavy games.
On the other side of the spectrum are games with no GMs at all; all gameplay are driven either by the computer
or by the interactions between players. Such games still need an active staff, but nowhere as much active
involvement. Allowing for solo-play with the computer also allows players to have fun when the number of active
players is low.
We want EvAdventure to work entirely without depending on human GMs. That said, there'd be nothing
stopping a GM from stepping in and run an adventure for some players should they want to.
### What is the staff hierarchy in your game? Is vanilla Evennia roles enough or do you need something else?
The default hierarchy is
- `Player` - regular players
- `Player Helper` - can create/edit help entries
- `Builder` - can use build commands
- `Admin` - can kick and ban accounts
- `Developer` - full access, usually also trusted with server access
There is also the _superuser_, the "owner" of the game you create when you first set up your database. This user
goes outside the regular hierarchy and should usually only.
We are okay with keeping this structure for our game.
### Should players be able to post out-of-characters on channels and via other means like bulletin-boards?
Evennia's _Channels_ are by default only available between _Accounts_. That is, for players to communicate with each
other. By default, the `public` channel is created for general discourse.
Channels are logged to a file and when you are coming back to the game you can view the history of a channel
in case you missed something.
> public Hello world!
[Public] MyName: Hello world!
But Channels can also be set up to work between Characters instead of Accounts. This would mean the channels
would have an in-game meaning:
- Members of a guild could be linked telepathically.
- Survivors of the apocalypse can communicate over walkie-talkies.
- Radio stations you can tune into or have to discover.
_Bulletin boards_ are a sort of in-game forum where posts are made publicly or privately. Contrary to a channel,
the messages are usually stored and are grouped into topics with replies. Evennia has no default bulletin-board
system.
In EvAdventure we will just use the default inter-account channels. We will also not be implementing any
bulletin boards.
## Building
### How will the world be built?
There are two main ways to handle this:
- Traditionally, from in-game with build-commands: This means builders creating content in their game
client. This has the advantage of not requiring Python skills nor server access. This can often be a quite
intuitive way to build since you are sort-of walking around in your creation as you build it. However, the
developer (you) must make sure to provide build-commands that are flexible enough for builders to be able to
create the content you want for your game.
- Externally (by batchcmds): Evennia's `batchcmd` takes a text file with Evennia Commands and executes them
in sequence. This allows the build process to be repeated and applied quickly to a new database during development.
It also allows builders to use proper text-editing tools rather than writing things line-by-line in their clients.
The drawback is that for their changes to go live they either need server access or they need to send their
batchcode to the game administrator so they can apply the changes. Or use version control.
- Externally (with batchcode or custom code): This is the "professional game development" approach. This gives the
builders maximum power by creating the content in Python using Evennia primitives. The `batchcode` processor
allows Evennia to apply and re-apply build-scripts that are raw Python modules. Again, this would require the
builder to have server access or to use version control to share their work with the rest of the development team.
In this tutorial, we will show examples of all these ways, but since we don't have a team of builders we'll
build the brunt of things using Evennia's Batchcode system.
### Can only privileged Builders create things or should regular players also have limited build-capability?
In some game styles, players have the ability to create objects and even script them. While giving regular users
the ability to create objects with in-built commands is easy and safe, actual code-creation (aka _softcode_ ) is
not something Evennia supports natively. Regular, untrusted users should never be allowed to execute raw Python
code (such as what you can do with the `py` command). You can
[read more about Evennia's stance on softcode here](../../../Concepts/Soft-Code.md). If you want users to do limited scripting,
it's suggested that this is accomplished by adding more powerful build-commands for them to use.
For our tutorial-game, we will only allow privileged builders to modify the world. The exception is crafting,
which we will limit to repairing broken items by combining them with other repair-related items.
## Systems
### Do you base your game off an existing RPG system or make up your own?
We will make use of [Open Adventure](http://www.geekguild.com/openadventure/), a simple 'old school' RPG-system
that is available for free under the Creative Commons license. We'll only use a subset of the rules from
the blue "basic" book. For the sake of keeping down the length of this tutorial we will limit what features
we will include:
- Only two 'archetypes' (classes) - Arcanist (wizard) and Warrior, these are examples of two different play
styles.
- Two races only (dwarves and elves), to show off how to implement races and race bonuses.
- No extra features of the races/archetypes such as foci and special feats. While these are good for fleshing
out a character, these will work the same as other bonuses and are thus not that instructive.
- We will add only a small number of items/weapons from the Open Adventure rulebook to show how it's done.
### What are the game mechanics? How do you decide if an action succeeds or fails?
Open Adventure's conflict resolution is based on adding a trait (such as Strength) with a random number in
order to beat a target. We will emulate this in code.
Having a "skill" means getting a bonus to that roll for a more narrow action.
Since the computer will need to know exactly what those skills are, we will add them more explicitly than
in the rules, but we will only add the minimum to show off the functionality we need.
### Does the flow of time matter in your game - does night and day change? What about seasons?
Most commonly, game-time runs faster than real-world time. There are
a few advantages with this:
- Unlike in a single-player game, you can't fast-forward time in a multiplayer game if you are waiting for
something, like NPC shops opening.
- Healing and other things that we know takes time will go faster while still being reasonably 'realistic'.
The main drawback is for games with slower roleplay pace. While you are having a thoughtful roleplaying scene
over dinner, the game world reports that two days have passed. Having a slower game time than real-time is
a less common, but possible solution for such games.
It is however _not_ recommended to let game-time exactly equal the speed of real time. The reason for this
is that people will join your game from all around the world, and they will often only be able to play at
particular times of their day. With a game-time drifting relative real-time, everyone will eventually be
able to experience both day and night in the game.
For this tutorial-game we will go with Evennia's default, which is that the game-time runs two times faster
than real time.
### Do you want changing, global weather or should weather just be set manually in roleplay?
A weather system is a good example of a game-global system that affects a subset of game entities
(outdoor rooms). We will not be doing any advanced weather simulation, but we'll show how to do
random weather changes happening across the game world.
### Do you want a coded world-economy or just a simple barter system? Or no formal economy at all?
We will allow for money and barter/trade between NPCs/Players and Player/Player, but will not care about
inflation. A real economic simulation could do things like modify shop prices based on supply and demand.
We will not go down that rabbit hole.
### Do you have concepts like reputation and influence?
These are useful things for a more social-interaction heavy game. We will not include them for this
tutorial however.
### Will your characters be known by their name or only by their physical appearance?
This is a common thing in RP-heavy games. Others will only see you as "The tall woman" until you
introduce yourself and they 'recognize' you with a name. Linked to this is the concept of more complex
emoting and posing.
Adding such a system from scratch is complex and way beyond the scope of this tutorial. However,
there is an existing Evennia contrib that adds all of this functionality and more, so we will
include that and explain briefly how it works.
## Rooms
### Is a simple room description enough or should the description be able to change?
Changing room descriptions for day and night, winder and summer is actually quite easy to do, but looks
very impressive. We happen to know there is also a contrib that helps with this, so we'll show how to
include that.
### Should the room have different statuses?
We will have different weather in outdoor rooms, but this will not have any gameplay effect - bow strings
will not get wet and fireballs will not fizzle if it rains.
### Can objects be hidden in the room? Can a person hide in the room?
We will not model hiding and stealth. This will be a game of honorable face-to-face conflict.
## Objects
### How numerous are your objects? Do you want large loot-lists or are objects just role playing props?
Since we are not going for a pure freeform RPG here, we will want objects with properties, like weapons
and potions and such. Monsters should drop loot even though our list of objects will not be huge.
### Is each coin a separate object or do you just store a bank account value?
Since we will use bartering, placing coin objects on one side of the barter makes for a simple way to
handle payments. So we will use coins as-objects.
### Do multiple similar objects form stacks and how are those stacks handled in that case?
Since we'll use coins, it's practical to have them and other items stack together. While Evennia does not
do this natively, we will make use of a contrib for this.
### Does an object have weight or volume (so you cannot carry an infinite amount of them)?
Limiting carrying weight is one way to stop players from hoarding. It also makes it more important
for players to pick only the equipment they need. Carrying limits can easily come across as
annoying to players though, so one needs to be careful with it.
Open Adventure rules include weight limits, so we will include them.
### Can objects be broken? Can they be repaired?
Item breakage is very useful for a game economy; breaking weapons adds tactical considerations (if it's not
too common, then it becomes annoying) and repairing things gives work for crafting players.
We wanted a crafting system, so this is what we will limit it to - repairing items using some sort
of raw materials.
### Can you fight with a chair or a flower or must you use a special 'weapon' kind of thing?
Traditionally, only 'weapons' could be used to fight with. In the past this was a useful
simplification, but with Python classes and inheritance, it's not actually more work to just
let all items in game work as a weapon in a pinch.
So for our game we will let a character use any item they want as a weapon. The difference will
be that non-weapon items will do less damage and also break and become unusable much quicker.
### Will characters be able to craft new objects?
Crafting is a common feature in multiplayer games. In code it usually means using a skill-check
to combine base ingredients from a fixed recipe in order to create a new item. The classic
example is to combine _leather straps_, a _hilt_, a _pommel_ and a _blade_ to make a new _sword_.
A full-fledged crafting system could require multiple levels of crafting, including having to mine
for ore or cut down trees for wood.
In our case we will limit our crafting to repairing broken items. To show how it's done, we will require
extra items (a recipe) in order to facilitate the repairs.
### Should mobs/NPCs have some sort of AI?
A rule of adding Artificial Intelligence is that with today's technology you should not hope to fool
anyone with it anytime soon. Unless you have a side-gig as an AI researcher, users will likely
not notice any practical difference between a simple state-machine and you spending a lot of time learning
how to train a neural net.
For this tutorial, we will show how to add a simple state-machine for monsters. NPCs will only be
shop-keepers and quest-gives so they won't need any real AI to speak of.
### Are NPCs and mobs different entities? How do they differ?
"Mobs" or "mobiles" are things that move around. This is traditionally monsters you can fight with, but could
also be city guards or the baker going to chat with the neighbor. Back in the day, they were often fundamentally
different these days it's often easier to just make NPCs and mobs essentially the same thing.
In EvAdventure, both Monsters and NPCs will be the same type of thing; A monster could give you a quest
and an NPC might fight you as a mob as well as trade with you.
### _Should there be NPCs giving quests? If so, how do you track Quest status?
We will design a simple quest system to track the status of ongoing quests.
## Characters
### Can players have more than one Character active at a time or are they allowed to multi-play?
Since Evennia differentiates between `Sessions` (the client-connection to the game), `Accounts`
and `Character`s, it natively supports multi-play. This is controlled by the `MULTISESSION_MODE`
setting, which has a value from `0` (default) to `3`.
- `0`- One Character per Account and one Session per Account. This means that if you login to the same
account from another client you'll be disconnected from the first. When creating a new account, a Character
will be auto-created with the same name as your Account. This is default mode and mimics legacy code bases
which had no separation between Account and Character.
- `1` - One Character per Account, multiple Sessions per Account. So you can connect simultaneously from
multiple clients and see the same output in all of them.
- `2` - Multiple Characters per Account, one Session per Character. This will not auto-create a same-named
Character for you, instead you get to create/choose between a number of Characters up to a max limit given by
the `MAX_NR_CHARACTERS` setting (default 1). You can play them all simultaneously if you have multiple clients
open, but only one client per Character.
- `3` - Multiple Characters per Account, Multiple Sessions per Character. This is like mode 2, except players
can control each Character from multiple clients, seeing the same output from each Character.
We will go with a multi-role game, so we will use `MULTISESSION_MODE=3` for this tutorial.
### How does the character-generation work?
There are a few common ways to do character generation:
- Rooms. This is the traditional way. Each room's description tells you what command to use to modify
your character. When you are done you move to the next room. Only use this if you have another reason for
using a room, like having a training dummy to test skills on, for example.
- A Menu. The Evennia _EvMenu_ system allows you to code very flexible in-game menus without needing to walk
between rooms. You can both have a step-by-step menu (a 'wizard') or allow the user to jump between the
steps as they please. This tends to be a lot easier for newcomers to understand since it doesn't require
using custom commands they will likely never use again after this.
- Questions. A fun way to build a character is to answer a series of questions. This is usually implemented
with a sequential menu.
For the tutorial we will use a menu to let the user modify each section of their character sheet in any order
until they are happy.
### How do you implement different "classes" or "races"?
The way classes and races work in most RPGs (as well as in OpenAdventure) is that they act as static 'templates'
that inform which bonuses and special abilities you have. This means that all we need to store on the
Character is _which_ class and _which_ race they have; the actual logic can sit in Python code and just
be looked up when we need it.
### If a Character can hide in a room, what skill will decide if they are detected?
Hiding means a few things.
- The Character should not appear in the room's description / character list
- Others hould not be able to interact with a hidden character. It'd be weird if you could do `attack <name>`
or `look <name>` if the named character is in hiding.
- There must be a way for the person to come out of hiding, and probably for others to search or accidentally
find the person (probably based on skill checks).
- The room will also need to be involved, maybe with some modifier as to how easy it is to hide in the room.
We will _not_ be including a hide-mechanic in EvAdventure though.
### What does the skill tree look like? Can a Character gain experience to improve? By killing enemies? Solving quests? By roleplaying?
Gaining experience points (XP) and improving one's character is a staple of roleplaying games. There are many
ways to implement this:
- Gaining XP from kills is very common; it's easy to let a monster be 'worth' a certain number of XP and it's
easy to tell when you should gain it.
- Gaining XP from quests is the same - each quest is 'worth' XP and you get them when completing the test.
- Gaining XP from roleplay is harder to define. Different games have tried a lot of different ways to do this:
- XP from being online - just being online gains you XP. This inflates player numbers but many players may
just be lurking and not be actually playing the game at any given time.
- XP from roleplaying scenes - you gain XP according to some algorithm analyzing your emotes for 'quality',
how often you post, how long your emotes are etc.
- XP from actions - you gain XP when doing things, anything. Maybe your XP is even specific to each action, so
you gain XP only for running when you run, XP for your axe skill when you fight with an axe etc.
- XP from fails - you only gain XP when failing rolls.
- XP from other players - other players can award you XP for good RP.
For EvAdventure we will use Open Adventure's rules for XP, which will be driven by kills and quest successes.
### May player-characters attack each other (PvP)?
Deciding this affects the style of your entire game. PvP makes for exciting gameplay but it opens a whole new
can of worms when it comes to "fairness". Players will usually accept dying to an overpowered NPC dragon. They
will not be as accepting if they perceive another player is perceived as being overpowered. PvP means that you
have to be very careful to balance the game - all characters does not have to be exactly equal but they should
all be viable to play a fun game with. PvP does not only mean combat though. Players can compete in all sorts of ways, including gaining influence in
a political game or gaining market share when selling their crafted merchandise.
For the EvAdventure we will support both Player-vs-environment combat and turn-based PvP. We will allow players
to barter with each other (so potentially scam others?) but that's the extent of it. We will focus on showing
off techniques and will not focus on making a balanced game.
### What are the penalties of defeat? Permanent death? Quick respawn? Time in prison?
This is another big decision that strongly affects the mood and style of your game.
Perma-death means that once your character dies, it's gone and you have to make a new one.
- It allows for true heroism. If you genuinely risk losing your character of two years to fight the dragon,
your triumph is an actual feat.
- It limits the old-timer dominance problem. If long-time players dies occationally, it will open things
up for newcomers.
- It lowers inflation, since the hoarded resources of a dead character can be removed.
- It gives capital punishment genuine discouraging power.
- It's realistic.
Perma-death comes with some severe disadvantages however.
- It's impopular. Many players will just not play a game where they risk losing their beloved character
just like that.
- Many players say they like the _idea_ of permadeath except when it could happen to them.
- It can limit roleplaying freedom and make people refuse to take any risks.
- It may make players even more reluctant to play conflict-driving 'bad guys'.
- Game balance is much, much more important when results are "final". This escalates the severity of 'unfairness'
a hundred-fold. Things like bugs or exploits can also lead to much more server effects.
For these reasons, it's very common to do hybrid systems. Some tried variations:
- NPCs cannot kill you, only other players can.
- Death is permanent, but it's difficult to actually die - you are much more likely to end up being severely
hurt/incapacitated.
- You can pre-pay 'insurance' to magically/technologically avoid actually dying. Only if don't have insurance will
you die permanently.
- Death just means harsh penalties, not actual death.
- When you die you can fight your way back to life from some sort of afterlife.
- You'll only die permanently if you as a player explicitly allows it.
For our tutorial-game we will not be messing with perma-death; instead your defeat will mean you will re-spawn
back at your home location with a fraction of your health.
## Conclusions
Going through the questions has helped us get a little bit more of a feel for the game we want to do. There are
many other things we could ask ourselves, but if we can cover these points we will be a good way towards a complete,
playable game!
Before starting to code in earnest a good coder should always do an inventory of all the stuff they _don't_ need
to code themselves. So in the next lesson we will check out what help we have from Evennia's _contribs_.

145
docs/source/Howtos/Beginner-Tutorial/Part2/Planning-Where-Do-I-Begin.md Normal file
View file

@ -0,0 +1,145 @@
# Where do I begin?
The good news is that following this Starting tutorial is a great way to begin making an Evennia game.
The bad news is that everyone's different and when it comes to starting your own game there is no
one-size-fits-all answer. Instead we will ask a series of questions
to help you figure this out for yourself. It will also help you evaluate your own skills and maybe
put some more realistic limits on how fast you can achieve your goals.
> The questions in this lesson do not really apply to our tutorial game since we know we are doing it
> to learn Evennia. If you just want to follow along with the technical bits you can skip this lesson and
> come back later when you feel ready to take on making your own game.
## What is your motivation for doing this?
So you want to make a game. First you need to make a few things clear to yourself.
Making a multiplayer online game is a _big_ undertaking. You will (if you are like most of us) be
doing it as a hobby, without getting paid. And you’ll be doing it for a long time.
So the very first thing you should ask yourself (and your team, if you have any) is
_why am I doing this_? Do some soul-searching here. Here are some possible answers:
- I want to earn recognition and fame from my online community and/or among my friends.
- I want to build the game so I can play and enjoy it myself.
- I want to build the same game I already play but without the bad people.
- I want to create a game so that I can control it and be the head honcho.
- A friend or online acquaintance talked me into working on it.
- I work on this because I’m paid to (wow!)
- I only build this for my own benefit or to see if I can pull it off.
- I want to create something to give back to the community I love.
- I want to use this project as a stepping-stone towards other projects (like a career in game design
or programming).
- I am interested in coding or server and network architectures, making a MUD just seems to be a good
way to teach myself.
- I want to build a commercial game and earn money.
- I want to fulfill a life-long dream of game making.
There are many other possibilities. How “solid” your answer is for a long-term development project
is up to you. The important point is that you ask yourself the question.
**Help someone else instead** - Maybe you should _not_ start a new project - maybe you're better off
helping someone else or improve on something that already exists. Or maybe you find you are more of a
game engine developer than a game designer.
**Driven by emotion** - Some answers may suggest that you are driven by emotions of revenge or disconcert. Be careful with that and
check so that's not your _only_ driving force. Those emotions may have abated later when the project
most needs your enthusiasm and motivation.
**Going commercial** - If your aim is to earn money, your design goals will likely be very different from
those of a person who only creates as a hobby or for their own benefit. You may also have a much stricter
timeline for release.
Whichever your motivation, you should at least have it clear in your own mind. It’s worth to make
sure your eventual team is on the same page too.
## What are your skills?
Once you have your motivations straight you need to take a stock of your own skills and the skills
available in your team, if you have any.
Your game will have two principal components and you will need skills to cater for both:
- The game engine / code base - Evennia in this case.
- The assets created for using the game engine (“the game world”)
### The game engine
The game engine is maintained and modified by programmers (coders). It represents the infrastructure
that runs the game - the network code, the protocol support, the handling of commands, scripting and
data storage.
If you are just evaluating Evennia, it's worth to do the following:
- Hang out in the community/forums/chat. Expect to need to ask a lot of “stupid” questions as you start
developing (hint: no question is stupid). Is this a community in which you would feel comfortable doing so?
- Keep tabs on the manual (you're already here).
- How's your Python skills? What are the skills in your team? Do you or your team already know it or are
you willing to learn? Learning the language as you go is not too unusual with Evennia devs, but expect it
to add development time. You will also be worse at predicting how 'hard' something is to do.
- If you don’t know Python, you should have gotten a few tastes from the first part of this tutorial. But
expect to have to refer to external online tutorials - there are many details of Python that will not be
covered.
### Asset creation
Compared to the level of work needed to produce professional graphics for an MMORPG, detailed text
assets for a mud are cheap to create. This is one of the many reasons muds are so well suited for a
small team.
This is not to say that making “professional” text content is easy though. Knowing how to write
imaginative and grammatically correct prose is only the minimal starting requirement. A good asset-
creator (traditionally called a “builder”) must also be able to utilize the tools of the game engine
to its fullest in order to script events, make quests, triggers and interactive, interesting
environments.
Assuming you are not coding all alone, your team’s in-house builders will be the first ones to actually
“use” your game framework and build tools. They will stumble on all the bugs. This means that you
need people who are just not “artsy” or “good with words”. Assuming coders and builders are not the
same people (common for early testing), builders need to be able to collaborate well and give clear
and concise feedback.
If you know your builders are not tech-savvy, you may need to spend more time making easier
build-tools and commands for them.
## So, where do I begin, then?
Right, after all this soul-searching and skill-inventory-checking, let’s go back to the original
question. And maybe you’ll find that you have a better feeling for the answer yourself already:
- Keep following this tutorial and spend the time
to really understand what is happening in the examples. Not only will this give you a better idea
of how parts hang together, it may also give you ideas for what is possible. Maybe something
is easier than you expected!
- Introduce yourself in the IRC/Discord chat and don't be shy to ask questions as you go through
the tutorial. Don't get hung up on trying to resolve something that a seasoned Evennia dev may
clear up for you in five minutes. Also, not all errors are your faults - it's possible the
tutorial is unclear or has bugs, asking will quickly bring those problems to light, if so.
- If Python is new to you, you should complement the tutorial with third-party Python references
so you can read, understand and replicate example code without being completely in the dark.
Once you are out of the starting tutorial, you'll be off to do your own thing.
- The starting tutorial cannot cover everything. Skim through the [Evennia docs](../../../index.md).
Even if you don't read everything, it gives you a feeling for what's available should you need
to look for something later. Make sure to use the search function.
- You can now start by expanding on the tutorial-game we will have created. In the last part there
there will be a list of possible future projects you could take on. Working on your own, without help
from a tutorial is the next step.
As for your builders, they can start getting familiar with Evennia's default build commands ... but
keep in mind that your game is not yet built! Don't set your builders off on creating large zone projects.
If they build anything at all, it should be small test areas to agree on a homogenous form, mood
and literary style.
## Conclusions
Remember that what kills a hobby game project will usually be your own lack of
motivation. So do whatever you can to keep that motivation burning strong! Even if it means
deviating from what you read in a tutorial like this one. Just get that game out there, whichever way
works best for you.
In the next lesson we'll go through some of the technical questions you need to consider. This should
hopefully help you figure out more about the game you want to make. In the lesson following that we'll
then try to answer those questions for the sake of creating our little tutorial game.