Beginner Tutorial

Tutorial Parts

Introduction

Getting set up.

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

Planning our tutorial game and what to think about when planning your own in the future.

Part 3: How we get there

Getting down to the meat of extending Evennia to make our game

Part 4: Using what we created

Building a tech-demo and world content to go with our code

Part 5: Showing the world

Taking our new game online and let players try it out

Welcome to Evennia! This multi-part Beginner Tutorial will help you get off the ground. It consists of five parts, each with several lessons. You can pick what seems interesting, but if you follow through to the end you will have created a little online game of your own to play and share with others!

Use the menu on the right to get the index of each tutorial-part. Use the next and previous links to step from lesson to lesson.

Things you need

• A Command line

• A MUD client (or web browser)

• A text-editor/IDE

• Evennia installed and a game-dir initialized

A Command line

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

Note that we usually only show forward-slashes / for file system paths. Windows users should mentally convert this to back-slashes \ instead.

A MUD client

You might already have a MUD-client you prefer. Check out the grid of supported clients 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 the terms ‘MUD’, ‘MU’ or ‘MU*’ interchangeably 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 - 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. 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 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 on to the first part of the tutorial. Good luck!

Click here to expand a list of all Beginner-Tutorial sections (all parts).

• Part 1: What we have
  • Lessons
    • 1. Using commands and building stuff
      • 1.1. Getting help
      • 1.2. Looking around
      • 1.3. Stepping Down From Godhood
      • 1.4. Creating an Object
      • 1.5. Get a Personality
      • 1.6. Pushing Your Buttons
      • 1.7. Making Yourself a House
      • 1.8. Reshuffling the World
      • 1.9. Adding a Help Entry
      • 1.10. Adding a World
    • 2. The Tutorial World
      • 2.1. Gameplay
        • 2.1.1. Gameplay hints
      • 2.2. Once you are done (or had enough)
      • 2.3. Uninstall the tutorial world
    • 3. Intro to using Python with Evennia
      • 3.1. Evennia Hello world
      • 3.2. Making some text ‘graphics’
        • 3.2.1. .format()
        • 3.2.2. f-strings
        • 3.2.3. Colored text
      • 3.3. Importing code from other modules
        • 3.3.1. Our first own function
      • 3.4. Sending text to others
      • 3.5. Parsing Python errors
      • 3.6. Passing arguments to functions
      • 3.7. Finding others to send to
      • 3.8. Multi-line py
      • 3.9. Other ways to test Python code
      • 3.10. ipython
      • 3.11. Conclusions
    • 4. Overview of your new Game Dir
      • 4.1. commands/
      • 4.2. server/
        • 4.2.1. server/logs/
        • 4.2.2. server/conf/
        • 4.2.3. typeclasses/
        • 4.2.4. web/
        • 4.2.5. world/
    • 5. Introduction to Python classes and objects
      • 5.1. Importing things
      • 5.2. On classes and objects
        • 5.2.1. Classes and instances
        • 5.2.2. What’s so good about objects?
        • 5.2.3. Classes can have children
      • 5.3. Summary
    • 6. Overview of the Evennia library
      • 6.1. Where is it?
      • 6.2. An example of exploring the library
    • 7. Making objects persistent
      • 7.1. Our first persistent object
        • 7.1.1. Making a new object by calling the class
        • 7.1.2. Creating using create_object
        • 7.1.3. Creating using create-command
      • 7.2. Typeclasses
        • 7.2.1. Examining and defaults
      • 7.3. Modifying ourselves
        • 7.3.1. A method on ourselves
        • 7.3.2. Attributes
        • 7.3.3. Setting things on new Characters
        • 7.3.4. Updating all Characters in a loop
      • 7.4. Extra Credits
      • 7.5. Conclusions
    • 8. Adding custom commands
      • 8.1. Creating a custom command
        • 8.1.1. Making our cmdset persistent
        • 8.1.2. Figuring out who to hit
      • 8.2. Summary
    • 9. Parsing Command input
      • 9.1. More advanced parsing
      • 9.2. Adding a Command to an object
        • 9.2.1. You need to hold the sword!
      • 9.3. Adding the Command to a default Cmdset
        • 9.3.1. Removing Commands
      • 9.4. Replace a default command
      • 9.5. Summary
    • 10. Creating things
      • 10.1. Creating Objects
      • 10.2. Creating Accounts
    • 11. Searching for things
      • 11.1. Main search functions
      • 11.2. Searching using Object.search
      • 11.3. What can be searched for
        • 11.3.1. Search by key
        • 11.3.2. Search by aliases
        • 11.3.3. Search by location
        • 11.3.4. Search by Tags
        • 11.3.5. Search by Attribute
        • 11.3.6. Search by Typeclass
        • 11.3.7. Search by dbref
      • 11.4. Finding objects relative each other
      • 11.5. Summary
    • 12. Advanced searching - Django Database queries
      • 12.1. Queryset field lookups
      • 12.2. Get that werewolf …
      • 12.3. Complex queries
      • 12.4. Annotations
      • 12.5. F-objects
      • 12.6. Grouping and returning only certain properties
      • 12.7. Conclusions
  • Table of Contents
    • 1. Using commands and building stuff
      • 1.1. Getting help
      • 1.2. Looking around
      • 1.3. Stepping Down From Godhood
      • 1.4. Creating an Object
      • 1.5. Get a Personality
      • 1.6. Pushing Your Buttons
      • 1.7. Making Yourself a House
      • 1.8. Reshuffling the World
      • 1.9. Adding a Help Entry
      • 1.10. Adding a World
    • 2. The Tutorial World
      • 2.1. Gameplay
        • 2.1.1. Gameplay hints
      • 2.2. Once you are done (or had enough)
      • 2.3. Uninstall the tutorial world
    • 3. Intro to using Python with Evennia
      • 3.1. Evennia Hello world
      • 3.2. Making some text ‘graphics’
        • 3.2.1. .format()
        • 3.2.2. f-strings
        • 3.2.3. Colored text
      • 3.3. Importing code from other modules
        • 3.3.1. Our first own function
      • 3.4. Sending text to others
      • 3.5. Parsing Python errors
      • 3.6. Passing arguments to functions
      • 3.7. Finding others to send to
      • 3.8. Multi-line py
      • 3.9. Other ways to test Python code
      • 3.10. ipython
      • 3.11. Conclusions
    • 4. Overview of your new Game Dir
      • 4.1. commands/
      • 4.2. server/
        • 4.2.1. server/logs/
        • 4.2.2. server/conf/
        • 4.2.3. typeclasses/
        • 4.2.4. web/
        • 4.2.5. world/
    • 5. Introduction to Python classes and objects
      • 5.1. Importing things
      • 5.2. On classes and objects
        • 5.2.1. Classes and instances
        • 5.2.2. What’s so good about objects?
        • 5.2.3. Classes can have children
      • 5.3. Summary
    • 6. Overview of the Evennia library
      • 6.1. Where is it?
      • 6.2. An example of exploring the library
    • 7. Making objects persistent
      • 7.1. Our first persistent object
        • 7.1.1. Making a new object by calling the class
        • 7.1.2. Creating using create_object
        • 7.1.3. Creating using create-command
      • 7.2. Typeclasses
        • 7.2.1. Examining and defaults
      • 7.3. Modifying ourselves
        • 7.3.1. A method on ourselves
        • 7.3.2. Attributes
        • 7.3.3. Setting things on new Characters
        • 7.3.4. Updating all Characters in a loop
      • 7.4. Extra Credits
      • 7.5. Conclusions
    • 8. Adding custom commands
      • 8.1. Creating a custom command
        • 8.1.1. Making our cmdset persistent
        • 8.1.2. Figuring out who to hit
      • 8.2. Summary
    • 9. Parsing Command input
      • 9.1. More advanced parsing
      • 9.2. Adding a Command to an object
        • 9.2.1. You need to hold the sword!
      • 9.3. Adding the Command to a default Cmdset
        • 9.3.1. Removing Commands
      • 9.4. Replace a default command
      • 9.5. Summary
    • 10. Creating things
      • 10.1. Creating Objects
      • 10.2. Creating Accounts
    • 11. Searching for things
      • 11.1. Main search functions
      • 11.2. Searching using Object.search
      • 11.3. What can be searched for
        • 11.3.1. Search by key
        • 11.3.2. Search by aliases
        • 11.3.3. Search by location
        • 11.3.4. Search by Tags
        • 11.3.5. Search by Attribute
        • 11.3.6. Search by Typeclass
        • 11.3.7. Search by dbref
      • 11.4. Finding objects relative each other
      • 11.5. Summary
    • 12. Advanced searching - Django Database queries
      • 12.1. Queryset field lookups
      • 12.2. Get that werewolf …
      • 12.3. Complex queries
      • 12.4. Annotations
      • 12.5. F-objects
      • 12.6. Grouping and returning only certain properties
      • 12.7. Conclusions
• Part 2: What we want
  • Lessons
    • Where do I begin?
      • What is your motivation for doing this?
      • What are your skills?
        • The game engine
        • Asset creation
      • So, where do I begin, then?
      • Conclusions
    • On Planning a Game
      • The steps
      • Planning
        • Administration
        • Building
        • Systems
        • Rooms
        • Objects / items
        • Characters
      • Coding and Tech demo
      • World Building
      • Alpha Release
      • Beta Release/Perpetual Beta
      • Congratulate yourself!
      • Planning our tutorial game
    • Planning our tutorial game
      • Game concept
      • Administration
        • Should your game rules be enforced by coded systems 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?
        • 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?
        • Should the room have different statuses?
        • Can objects be hidden in the room? Can a person hide in the room?
      • Objects
        • How numerous are your objects? Do you want large loot-lists or are objects just role playing props?
        • Is each coin a separate object or do you just store a bank account value?
        • Do multiple similar objects form stack 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 special ‘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?
        • How do you implement different “classes” or “races”?
        • 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?
      • Conclusions
  • Table of Contents
    • Where do I begin?
      • What is your motivation for doing this?
      • What are your skills?
        • The game engine
        • Asset creation
      • So, where do I begin, then?
      • Conclusions
    • On Planning a Game
      • The steps
      • Planning
        • Administration
        • Building
        • Systems
        • Rooms
        • Objects / items
        • Characters
      • Coding and Tech demo
      • World Building
      • Alpha Release
      • Beta Release/Perpetual Beta
      • Congratulate yourself!
      • Planning our tutorial game
    • Planning our tutorial game
      • Game concept
      • Administration
        • Should your game rules be enforced by coded systems 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?
        • 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?
        • Should the room have different statuses?
        • Can objects be hidden in the room? Can a person hide in the room?
      • Objects
        • How numerous are your objects? Do you want large loot-lists or are objects just role playing props?
        • Is each coin a separate object or do you just store a bank account value?
        • Do multiple similar objects form stack 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 special ‘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?
        • How do you implement different “classes” or “races”?
        • 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?
      • Conclusions
• Part 3: How we get there
  • Lessons
    • Code structure and Utilities
      • Folder structure
      • Enums
      • Utility module
      • Testing
        • Running your test
      • Summary
    • Rules and dice rolling
      • Summary of Knave rules
      • Making a rule module
      • Rolling dice
        • Generic dice roller
        • Rolling with advantage
        • Saving throws
        • Opposed saving throw
        • Morale check
        • Roll for Healing
        • Rolling on a table
        • Roll for death
      • Testing
        • Mocking and patching
      • Summary
    • Player Characters
      • Inheritance structure
      • Living mixin class
      • Character class
        • Funcparser inlines
        • Backtracking
      • Connecting the Character with Evennia
      • Unit Testing
      • About races and classes
      • Summary
    • In-game Objects and items
      • New Enums
      • The base object
        • Using Attributes or not
        • Creating tags in at_object_creation
      • Other object types
      • Consumables
      • Weapons
      • Magic
      • Armor
      • Your Bare hands
      • Testing and Extra credits
    • Handling Equipment
      • EquipmentHandler that saves
      • Connecting the EquipmentHandler
      • Expanding the Equipmenthandler
      • .validate_slot_usage
        • .max_slots
        • .count_slots
        • Validating slots
      • .add and .remove
      • Moving things around
      • Get everything
      • Weapon and armor
      • Extra credits
      • Unit Testing
      • Summary
    • Character Generation
      • How it will work
      • Random tables
      • Storing state of the menu
        • Showing the sheet
        • Apply character
      • Initializing EvMenu
      • Main Node: Choosing what to do
      • Node: Changing your name
      • Node: Swapping Abilities around
      • Node: Creating the Character
      • Tying the nodes together
      • Conclusions
    • In-game Rooms
    • Non-Player-Characters (NPCs)
    • Game Quests
    • In-game Shops
    • Dynamically generated Dungeon
    • In-game Commands
  • Table of Contents
    • Code structure and Utilities
      • Folder structure
      • Enums
      • Utility module
      • Testing
        • Running your test
      • Summary
    • Rules and dice rolling
      • Summary of Knave rules
      • Making a rule module
      • Rolling dice
        • Generic dice roller
        • Rolling with advantage
        • Saving throws
        • Opposed saving throw
        • Morale check
        • Roll for Healing
        • Rolling on a table
        • Roll for death
      • Testing
        • Mocking and patching
      • Summary
    • Player Characters
      • Inheritance structure
      • Living mixin class
      • Character class
        • Funcparser inlines
        • Backtracking
      • Connecting the Character with Evennia
      • Unit Testing
      • About races and classes
      • Summary
    • In-game Objects and items
      • New Enums
      • The base object
        • Using Attributes or not
        • Creating tags in at_object_creation
      • Other object types
      • Consumables
      • Weapons
      • Magic
      • Armor
      • Your Bare hands
      • Testing and Extra credits
    • Handling Equipment
      • EquipmentHandler that saves
      • Connecting the EquipmentHandler
      • Expanding the Equipmenthandler
      • .validate_slot_usage
        • .max_slots
        • .count_slots
        • Validating slots
      • .add and .remove
      • Moving things around
      • Get everything
      • Weapon and armor
      • Extra credits
      • Unit Testing
      • Summary
    • Character Generation
      • How it will work
      • Random tables
      • Storing state of the menu
        • Showing the sheet
        • Apply character
      • Initializing EvMenu
      • Main Node: Choosing what to do
      • Node: Changing your name
      • Node: Swapping Abilities around
      • Node: Creating the Character
      • Tying the nodes together
      • Conclusions
    • In-game Rooms
    • Non-Player-Characters (NPCs)
    • Game Quests
    • In-game Shops
    • Dynamically generated Dungeon
    • In-game Commands
• Part 4: Using what we created
  • Lessons
  • Table of Contents
• Part 5: Showing the world
  • Lessons
    • Add a simple new web page
      • Create the view
      • The HTML page
      • The URL
    • Web Tutorial
      • A Basic Overview
      • Changing the logo on the front page
      • Changing the Front Page’s Text
      • Further reading
  • Table of Contents
    • Add a simple new web page
      • Create the view
      • The HTML page
      • The URL
    • Web Tutorial
      • A Basic Overview
      • Changing the logo on the front page
      • Changing the Front Page’s Text
      • Further reading