NPC AI module for EvAdventure (WIP)

This implements a state machine for the NPCs, where it uses inputs from the game to determine what to do next. The AI works on the concept of being ‘ticks’, at which point, the AI will decide to move between different ‘states’, performing different ‘actions’ within each state until changing to another state. The odds of changing between states and performing actions are weighted, allowing for an AI agent to be more or less likely to perform certain actions.

The state machine is fed a dictionary of states and their transitions, and a dictionary of available actions to choose between.

    "states": {
        "state1": {"action1": odds, "action2": odds, ...},
        "state2": {"action1": odds, "action2": odds, ...}, ...
    "transition": {
        "state1": {"state2": "odds, "state3": odds, ...},
        "state2": {"state1": "odds, "state3": odds, ...}, ...

The NPC class needs to look like this:

class NPC(DefaultCharacter):

    # ...

    def ai(self):
        return AIHandler(self)

    def ai_roam(self, action):
        # perform the action within the current state ai.state

    def ai_hunt(self, action):
        # etc
class evennia.contrib.tutorials.evadventure.ai.AIHandler(obj)[source]

Bases: object

AIHandler class. This should be placed on the NPC object, and will handle the state machine, including transitions and actions.

Add to typeclass with @lazyproperty:

class NPC(DefaultCharacter):

ai_states = {…}

# …

@lazyproperty def ai(self):

return AIHandler(self)


Initialize self. See help(type(self)) for accurate signature.

property state

Return the current state of the AI.


str – Current state of the AI.

property states

Return the states dictionary for the AI.


dict – States dictionary for the AI.

property transitions

Return the transitions dictionary for the AI.


dict – Transitions dictionary for the AI.

add_aidict(aidict, force=False)[source]

Add an AI dictionary to the AI handler, if one doesn’t already exist.

  • aidict (dict) – AI dictionary to add.

  • force (bool, optional) – Force adding the AI dictionary, even if one already exists on

  • handler. (this) –

adjust_transition_probability(state_start, state_end, odds)[source]

Adjust the transition probability between two states.

  • state_start (str) – State to start from.

  • state_end (str) – State to end at.

  • odds (int) – New odds for the transition.


This will normalize the odds across the other transitions from the starting state.


Get the next state for the AI.


str – Next state for the AI.


Get the next action for the AI within the current state.


str – Next action for the AI.


Execute the next ai action in the current state.

This assumes that each available state exists as a method on the object, named ai_<state_name>, taking an optional argument of the next action to perform. The method will itself update the state or transition weights through this handler.

Some states have in-built state transitions, via the special “change_state” action.