Beginner Tutorial

Beginner 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 consider when planning your own.

• Part 3: How We Get There
  Getting down to the meat of extending Evennia to make your 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 letting players try it out.

Welcome to Evennia! This multi-part Beginner Tutorial will help get you off the ground and running.

You may choose topics that seem interesting but, if you follow this tutorial through to the end, you will have created your own small online game to play and share with others!

Use the menu on the right to navigate the index of each of the tutorial’s parts. Use the next and previous links at the top/bottom right of each page to jump between lessons.

Things You Need

• A command line interface

• A MUD client (or web browser)

• A text-editor/IDE

• Evennia installed and a game-dir initialized

A Command Line Interface

You need to know how to find the terminal/console in your OS. The Evennia server can be controlled from in-game, but you will realistically need to use the command-line interface to get anywhere. Here are some starters:

• Online Intro to the Command line for different OS:es

Note that the documentation typically uses forward-slashes (/) for file system paths. Windows users should convert these to back-slashes (\) instead.

A Fresh Game-Dir?

You should make sure that you have successfully installed Evennia. If you followed the instructions, you will have already created a game-dir. The documentation will continue to refer to this game-dir as mygame, so you may want to re-use it or make a new one specific to this tutorial only – it’s up to you.

If you already have a game-dir and want a new one specific to this tutorial, use the evennia stop command to halt the running server. Then, initialize a new game-dir somewhere else (not inside the previous game-dir!).

A MUD Client

You may already have a preferred MUD client. Check out the grid of supported clients. Or, if telnet’s not your thing, you may also simply use Evennia’s web-client in your preferred browser.

Make sure you know how to connect and log in to your locally running Evennia server.

In this documentation we often interchangeably use the terms ‘MUD’, ‘MU’, and ‘MU*’ to represent all the historically different forms of text-based multiplayer game-styles (i.e., MUD, MUX, MUSH, MUCK, MOO, etc.). Evennia can be used to create any of these game-styles… and more!

A Text Editor or IDE

You need a text editor application to edit Python source files. Most anything that can edit and output raw text should work (…so not Microsoft Word).

• Here’s a blog post summing up a variety of text editor options - 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 it is not suitable for beginners.

Important

Use Spaces, Not Tabs< br/> Make sure to configure your text editor so that pressing the ‘Tab’ key inserts 4 spaces rather than a tab-character. Because Python is whitespace-aware, this simple practice will make your life much easier.

Running python commands outside game (optional)

This tutorial will primarily assume you are experimenting with Python through your game client, using the in-game py command. But you can also explore Python instructions outside of the game. Run the following from your game dir folder:

$ evennia shell 

The evennia shell console is convenient for experimenting with Python. But note that if you manipulate database objects from evennia shell, those changes will not be visible from inside the game until you reload the server. Similarly changes in-game may not visible to the evennia shell console until restarting it. As a guideline, use evennia shell for testing things out. Don’t use it to change the state of a running game. The beginner tutorial uses the in-game py command to avoid confusion.

This will open an Evennia/Django aware python shell. You should use this instead of just running vanilla python since the latter won’t set up Django for you and you won’t be able to import evennia without a lot of extra setup. For an even nicer experience, it’s recommended you install the ipython program:

 $ pip install ipython3

The evennia shell command will use ipython automatically if installed.

---

You should now be ready to move on to the first part of the Beginner Tutorial! (In the future, use the previous | next buttons on the top/bottom of the page to progress.)

Click here to see the full index of all parts and lessons of the Beginner-Tutorial.

• 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.2.4. A look at multiple inheritance
      • 5.3. Summary
    • 6. Overview of the Evennia library
      • 6.1. Where is it?
      • 6.2. An example of exploring the library
      • 6.3. Conclusions
    • 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 objects
        • 7.2.2. Default typeclasses
      • 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. Add the echo command to the default cmdset
        • 8.1.3. 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 Rooms, Characters and Exits
        • 10.2.1. Linking Exits and Rooms in code
      • 10.3. Creating Accounts
      • 10.4. Creating Channels
      • 10.5. Creating Scripts
      • 10.6. Conclusion
    • 11. Searching for things
      • 11.1. Searching using Object.search
      • 11.2. Main search functions
      • 11.3. Understanding object relationships
      • 11.4. What can be searched for
        • 11.4.1. Search by key
        • 11.4.2. Search by aliases
        • 11.4.3. Search by location
        • 11.4.4. Search by Tags
        • 11.4.5. Search by Attribute
        • 11.4.6. Search by Typeclass
        • 11.4.7. Search by dbref
      • 11.5. Summary
    • 12. Advanced searching - Django Database queries
      • 12.1. Queryset field lookups
      • 12.2. Let’s get that werewolf …
      • 12.3. Queries with OR or NOT
      • 12.4. Annotations
      • 12.5. F-objects
      • 12.6. Grouping and returning only certain properties
      • 12.7. Conclusions
    • 13. Building a chair you can sit on
      • 13.1. Make us not able to move while sitting
      • 13.2. Making the Chair itself
        • 13.2.1. Sitting on or in?
        • 13.2.2. Extra credits
      • 13.3. Adding commands
        • 13.3.1. Command variant 1: Commands on the chair
        • 13.3.2. Command variant 2: Command on Character
      • 13.4. Conclusions
• Part 2: What We Want
  • Lessons
    • 1. Where do I begin?
      • 1.1. What is your motivation for doing this?
      • 1.2. What are your skills?
        • 1.2.1. The game engine
        • 1.2.2. Asset creation
      • 1.3. So, where do I begin, then?
      • 1.4. Conclusions
    • 2. On Planning a Game
      • 2.1. The steps
      • 2.2. Planning
        • 2.2.1. Administration
        • 2.2.2. Building
        • 2.2.3. Systems
        • 2.2.4. Rooms
        • 2.2.5. Objects / items
        • 2.2.6. Characters
      • 2.3. Coding and Tech demo
      • 2.4. World Building
      • 2.5. Alpha Release
      • 2.6. Beta Release/Perpetual Beta
      • 2.7. Congratulate yourself!
      • 2.8. Planning our tutorial game
    • 3. Planning our tutorial game
      • 3.1. Game concept
      • 3.2. Administration
        • 3.2.1. Should your game rules be enforced by coded systems by human game masters?
        • 3.2.2. What is the staff hierarchy in your game? Is vanilla Evennia roles enough or do you need something else?
        • 3.2.3. Should players be able to post out-of-characters on channels and via other means like bulletin-boards?
      • 3.3. Building
        • 3.3.1. How will the world be built?
        • 3.3.2. Can only privileged Builders create things or should regular players also have limited build-capability?
      • 3.4. Systems
        • 3.4.1. Do you base your game off an existing RPG system or make up your own?
        • 3.4.2. What are the game mechanics? How do you decide if an action succeeds or fails?
        • 3.4.3. Does the flow of time matter in your game - does night and day change? What about seasons?
        • 3.4.4. Do you want changing, global weather or should weather just be set manually in roleplay?
        • 3.4.5. Do you want a coded world-economy or just a simple barter system? Or no formal economy at all?
        • 3.4.6. Do you have concepts like reputation and influence?
        • 3.4.7. Will your characters be known by their name or only by their physical appearance?
      • 3.5. Rooms
        • 3.5.1. Is a simple room description enough or should the description be able to change?
        • 3.5.2. Should the room have different statuses?
        • 3.5.3. Can objects be hidden in the room? Can a person hide in the room?
      • 3.6. Objects
        • 3.6.1. How numerous are your objects? Do you want large loot-lists or are objects just role playing props?
        • 3.6.2. Is each coin a separate object or do you just store a bank account value?
        • 3.6.3. Do multiple similar objects form stack and how are those stacks handled in that case?
        • 3.6.4. Does an object have weight or volume (so you cannot carry an infinite amount of them)?
        • 3.6.5. Can objects be broken? Can they be repaired?
        • 3.6.6. Can you fight with a chair or a flower or must you use a special ‘weapon’ kind of thing?
        • 3.6.7. Will characters be able to craft new objects?
        • 3.6.8. Should mobs/NPCs have some sort of AI?
        • 3.6.9. Are NPCs and mobs different entities? How do they differ?
        • 3.6.10. _Should there be NPCs giving quests? If so, how do you track Quest status?
      • 3.7. Characters
        • 3.7.1. Can players have more than one Character active at a time or are they allowed to multi-play?
        • 3.7.2. How does the character-generation work?
        • 3.7.3. How do you implement different “classes” or “races”?
        • 3.7.4. If a Character can hide in a room, what skill will decide if they are detected?
        • 3.7.5. What does the skill tree look like? Can a Character gain experience to improve? By killing enemies? Solving quests? By roleplaying?
        • 3.7.6. May player-characters attack each other (PvP)?
        • 3.7.7. What are the penalties of defeat? Permanent death? Quick respawn? Time in prison?
      • 3.8. Conclusions
• Part 3: How We Get There (Example Game)
  • Lessons
    • 1. Code Structure and Utilities
      • 1.1. Folder Structure
      • 1.2. Enums
      • 1.3. Utility Module
      • 1.4. Testing
        • 1.4.1. Running your Test
      • 1.5. Summary
    • 2. Rules and dice rolling
      • 2.1. Summary of Knave rules
      • 2.2. Making a rule module
      • 2.3. Rolling dice
        • 2.3.1. Generic dice roller
        • 2.3.2. Rolling with advantage
        • 2.3.3. Saving throws
        • 2.3.4. Opposed saving throw
        • 2.3.5. Morale check
        • 2.3.6. Roll for Healing
        • 2.3.7. Rolling on a table
        • 2.3.8. Roll for death
      • 2.4. Testing
        • 2.4.1. Mocking and patching
      • 2.5. Summary
    • 3. Player Characters
      • 3.1. Inheritance structure
      • 3.2. Living mixin class
      • 3.3. Character class
        • 3.3.1. Funcparser inlines
        • 3.3.2. Backtracking
      • 3.4. Connecting the Character with Evennia
      • 3.5. Unit Testing
      • 3.6. About races and classes
      • 3.7. Summary
    • 4. In-game Objects and items
      • 4.1. New Enums
      • 4.2. The base object
        • 4.2.1. Using Attributes or not
        • 4.2.2. Creating tags in at_object_creation
      • 4.3. Other object types
      • 4.4. Consumables
      • 4.5. Weapons
      • 4.6. Magic
      • 4.7. Armor
      • 4.8. Your Bare hands
      • 4.9. Testing and Extra credits
    • 5. Handling Equipment
      • 5.1. EquipmentHandler that saves
      • 5.2. Connecting the EquipmentHandler
      • 5.3. Expanding the Equipmenthandler
      • 5.4. .validate_slot_usage
        • 5.4.1. .max_slots
        • 5.4.2. .count_slots
        • 5.4.3. Validating slots
      • 5.5. .add and .remove
      • 5.6. Moving things around
      • 5.7. Get everything
      • 5.8. Weapon and armor
        • 5.8.1. Fixing the Character class
      • 5.9. Extra credits
      • 5.10. Unit Testing
      • 5.11. Summary
    • 6. Character Generation
      • 6.1. How it will work
      • 6.2. Random tables
      • 6.3. Storing state of the menu
        • 6.3.1. Showing the sheet
        • 6.3.2. Apply character
      • 6.4. Initializing EvMenu
      • 6.5. Main Node: Choosing what to do
      • 6.6. Node: Changing your name
      • 6.7. Node: Swapping Abilities around
      • 6.8. Node: Creating the Character
      • 6.9. Tying the nodes together
      • 6.10. Conclusions
    • 7. In-game Rooms
      • 7.1. The base room
      • 7.2. PvP room
      • 7.3. Adding a room map
      • 7.4. Adding life to a room
      • 7.5. Testing
      • 7.6. Conclusion
    • 8. Non-Player-Characters
      • 8.1. The NPC base class
      • 8.2. Testing
      • 8.3. Conclusions
    • 9. Combat base framework
      • 9.1. CombatHandler
        • 9.1.1. CombatHandler.get_or_create_combathandler
        • 9.1.2. CombatHandler.msg
        • 9.1.3. Combathandler.get_combat_summary
      • 9.2. Actions
      • 9.3. Action dicts
      • 9.4. Action classes
        • 9.4.1. Hold Action
        • 9.4.2. Attack Action
        • 9.4.3. Stunt Action
        • 9.4.4. Use Item Action
        • 9.4.5. Wield Action
      • 9.5. Testing
      • 9.6. Conclusions
    • 10. Twitch Combat
      • 10.1. General principle
      • 10.2. Twitch combat handler
        • 10.2.1. Getting the sides of combat
        • 10.2.2. Tracking Advantage / Disadvantage
        • 10.2.3. Queue action
        • 10.2.4. Execute an action
        • 10.2.5. Checking and stopping combat
      • 10.3. Commands
        • 10.3.1. Base Combat class
        • 10.3.2. In-combat look command
        • 10.3.3. Hold command
        • 10.3.4. Attack command
        • 10.3.5. Using items
        • 10.3.6. Wielding new weapons and equipment
      • 10.4. Grouping Commands for use
        • 10.4.1. Combat startup and cleanup
      • 10.5. Unit Testing
      • 10.6. A small combat test
      • 10.7. Conclusions
    • 11. Turnbased Combat
      • 11.1. General Principle
      • 11.2. Turnbased combat handler
        • 11.2.1. Getting the sides of combat
        • 11.2.2. Tracking Advantage/Disadvantage
        • 11.2.3. Adding and removing combatants
        • 11.2.4. Flee Action
        • 11.2.5. Queue action
        • 11.2.6. Execute an action and tick the round
        • 11.2.7. Check and stop combat
        • 11.2.8. Start combat
      • 11.3. Using EvMenu for the combat menu
      • 11.4. Menu for Turnbased combat
        • 11.4.1. The node index
        • 11.4.2. Getting or setting the combathandler
        • 11.4.3. Queue an action
        • 11.4.4. Rerun a node
        • 11.4.5. Stepping through the wizard
        • 11.4.6. Choosing targets and recipients
        • 11.4.7. Choose an Ability
        • 11.4.8. Choose an item to use or wield
        • 11.4.9. The main menu node
      • 11.5. Attack Command
      • 11.6. Making sure the menu stops
      • 11.7. Testing
      • 11.8. A small combat test
      • 11.9. Conclusions
    • 12. NPC and monster AI
      • 12.1. Our requirements
      • 12.2. The AIHandler
        • 12.2.1. More helpers on the AI handler
      • 12.3. Adding AI to an entity
        • 12.3.1. Idle state
        • 12.3.2. Roam state
        • 12.3.3. Flee state
        • 12.3.4. Combat state
      • 12.4. Unit Testing
      • 12.5. Conclusions
    • 13. Procedurally generated Dungeon
      • 13.1. Design Concept
        • 13.1.1. The starting room
        • 13.1.2. Generating new branch rooms
        • 13.1.3. Making the dungeon dangerous
        • 13.1.4. Difficulty scaling
      • 13.2. Start Implementation
      • 13.3. Basic Dungeon rooms
      • 13.4. Dungeon exits
      • 13.5. Dungeon Branch and the xy grid
        • 13.5.1. Grid coordinates and exit mappings
          • 13.5.1.1. Base structure of the Dungeon branch script
        • 13.5.2. A note about the room-generator
        • 13.5.3. Deleting a dungeon branch
        • 13.5.4. Creating a new dungeon room
      • 13.6. Back to the dungeon exit class
      • 13.7. Starting room exits
      • 13.8. Utility scripts
      • 13.9. Starting room
      • 13.10. Testing
      • 13.11. Conclusions
    • 14. Game Quests
      • 14.1. The Quest Handler
      • 14.2. The Quest class
        • 14.2.1. Example quest
        • 14.2.2. A useful Command
      • 14.3. Testing
      • 14.4. Conclusions
    • 15. In-game Shops
    • 16. In-game Commands
• Part 4: Using What We Created
  • Lessons
    • 1. Unimplemented
• Part 5: Showing the World
  • Lessons
    • 1. Add a simple new web page
      • 1.1. Create the view
      • 1.2. The HTML page
      • 1.3. The URL