# evennia.contrib.tutorials.evadventure.dungeon

Dungeon system

This creates a procedurally generated dungeon.

The dungone originates in an entrance room with exits that spawn a new dungeon connection every X minutes. As long as characters go through the same exit within that time, they will all end up in the same dungeon ‘branch’, otherwise they will go into separate, un-connected dungeon ‘branches’. They can always go back to the start room, but this will become a one-way exit back.

When moving through the dungeon, a new room is not generated until characters decided to go in that direction. Each room is tagged with the specific ‘instance’ id of that particular branch of dungon. When no characters remain in the branch, the branch is deleted.

Each room in the dungeon starts with a Tag not_clear; while this is set, all exits out of the room (not the one they came from) is blocked. When whatever problem the room offers has been solved (such as a puzzle or a battle), the tag is removed and the player(s) can choose which exit to leave through.

`evennia.contrib.tutorials.evadventure.dungeon.``random`() → x in the interval [0, 1).

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonRoom`(*args, **kwargs)

  Bases: `evennia.contrib.tutorials.evadventure.rooms.EvAdventureRoom`

  Dangerous dungeon room.

  `allow_combat` = True
  `allow_death` = True
  `back_exit`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `dungeon_orchestrator`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `xy_coords`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  property `is_room_clear`
  `clear_room`()
  `at_object_creation`()

    Set the not_clear tag on the room. This is removed when the room is ‘cleared’, whatever that means for each room.

    We put this here rather than in the room-creation code so we can override easier (for example we may want an empty room which auto-clears).

  `get_display_footer`(looker, **kwargs)

    Show if the room is ‘cleared’ or not as part of its description.

  exception `DoesNotExist`

    Bases: `evennia.contrib.tutorials.evadventure.rooms.EvAdventureRoom.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.contrib.tutorials.evadventure.rooms.EvAdventureRoom.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonRoom'
  `typename` = 'EvAdventureDungeonRoom'

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonExit`(*args, **kwargs)

  Bases: `evennia.objects.objects.DefaultExit`

  Dungeon exit. This will not create the target room until it’s traversed. It must be created referencing the dungeon_orchestrator it belongs to.

  `at_object_creation`()

    We want to block progressing forward unless the room is clear.

  `at_traverse`(traversing_object, target_location, **kwargs)

    Called when traversing. target_location will be None if the target was not yet created.

  `at_failed_traverse`(traversing_object, **kwargs)

    Called when failing to traverse.

  exception `DoesNotExist`

    Bases: `evennia.objects.objects.DefaultExit.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.objects.objects.DefaultExit.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonExit'
  `typename` = 'EvAdventureDungeonExit'

`evennia.contrib.tutorials.evadventure.dungeon.``room_generator`(dungeon_orchestrator, depth, coords)

  Plugin room generator

  This default one returns the same empty room.

  Parameters

    - dungeon_orchestrator (EvAdventureDungeonOrchestrator) – The current orchestrator.

    - depth (int) – The ‘depth’ of the dungeon (radial distance from start room) this new room will be placed at.

    - coords (tuple) – The (x,y) coords that the new room will be created at.

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonOrchestrator`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  One script is created per dungeon ‘branch’ created. The orchestrator is responsible for determining what is created next when a character enters an exit within the dungeon.

  `max_unexplored_exits` = 2
  `max_new_exits_per_room` = 2
  `rooms`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `unvisited_exits`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `highest_depth`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `last_updated`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `room_generator`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `xy_grid`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `start_room`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `register_exit_traversed`(exit)

    Tell the system the given exit was traversed. This allows us to track how many unvisited paths we have so as to not have it grow exponentially.

  `create_out_exit`(location, exit_direction='north')

    Create outgoing exit from a room. The target room is not yet created.

  `delete`()

    Clean up the entire dungeon along with the orchestrator.

  `new_room`(from_exit)

    Create a new Dungeon room leading from the provided exit.

    Parameters

      from_exit (Exit) – The exit leading to this new room.

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonOrchestrator'
  `typename` = 'EvAdventureDungeonOrchestrator'

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonStartRoomExit`(*args, **kwargs)

  Bases: `evennia.objects.objects.DefaultExit`

  Traversing this exit will either lead to an existing dungeon branch or create a new one.

  Since exits need to have a destination, we start out having them loop back to the same location and change this whenever someone actually traverse them. The act of passing through creates a room on the other side.

  `reset_exit`()

    Flush the exit, so next traversal creates a new dungeon branch.

  `at_traverse`(traversing_object, target_location, **kwargs)

    When traversing create a new orchestrator if one is not already assigned.

  exception `DoesNotExist`

    Bases: `evennia.objects.objects.DefaultExit.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.objects.objects.DefaultExit.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonStartRoomExit'
  `typename` = 'EvAdventureDungeonStartRoomExit'

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureStartRoomResetter`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  Simple ticker-script. Introduces a chance of the room’s exits cycling every interval.

  `at_script_creation`()

    Only called once, when script is first created.

  `at_repeat`()

    Called every time the script repeats.

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureStartRoomResetter'
  `typename` = 'EvAdventureStartRoomResetter'

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonBranchDeleter`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  Cleanup script. After some time a dungeon branch will ‘collapse’, forcing all players in it back to the start room.

  `branch_max_life`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `at_script_creation`()

    Only called once, when script is first created.

  `at_repeat`()

    Go through all dungeon-orchestrators and find which ones are too old.

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonBranchDeleter'
  `typename` = 'EvAdventureDungeonBranchDeleter'

class `evennia.contrib.tutorials.evadventure.dungeon.``EvAdventureDungeonStartRoom`(*args, **kwargs)

  Bases: `evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonRoom`

  The start room is the only permanent part of the dungeon. Exits leading from this room (except one leading back outside) each create/links to a separate dungeon branch/instance.

  - A script will reset each exit every 5 mins; after that time, entering the exit will spawn

      a new branch-instance instead of leading to the one before.

  - Another script will check age of branch instance every hour; once an instance has been

      inactive for a week, it will ‘collapse’, forcing everyone inside back to the start room.

  The actual exits should be created in the build script.

  `recycle_time` = 300
  `branch_check_time` = 3600
  `branch_max_life` = 604800
  `room_generator`

    Attribute property descriptor. Allows for specifying Attributes as Django-like ‘fields’ on the class level. Note that while one can set a lock on the Attribute, there is no way to check said lock when accessing via the property - use the full AttributeHandler if you need to do access checks.

    Example:

        class Character(DefaultCharacter):
            foo = AttributeProperty(default="Bar")

  `get_display_footer`(looker, **kwargs)

    Show if the room is ‘cleared’ or not as part of its description.

  `at_object_creation`()

    Set the not_clear tag on the room. This is removed when the room is ‘cleared’, whatever that means for each room.

    We put this here rather than in the room-creation code so we can override easier (for example we may want an empty room which auto-clears).

  `at_object_receive`(obj, source_location, **kwargs)

    Make sure to clean the dungeon branch-tag from characters when leaving a dungeon branch.

  exception `DoesNotExist`

    Bases: `evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonRoom.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonRoom.MultipleObjectsReturned`

  `path` = 'evennia.contrib.tutorials.evadventure.dungeon.EvAdventureDungeonStartRoom'
  `typename` = 'EvAdventureDungeonStartRoom'