Story Files

#Story files

The game is broken up into stories. From the title screen you can choose which story to explore. At the moment, each story has its own locations, monsters, character classes, and skills.

A story file is a json file which describese all of the attributes of the story. Adding a new story simply involves creating the appropriate json file and including it in the list in stories.txt. The wscript file has been modified to automatically process the stories and include them in the build.

##Main Story Object

• "id": <integer> # This needs to be unique across all stories included. It is used to index persisted storage.
• "version": <integer> # Should be updated whenever the story fundamentally changes. This is used to invalidate existing persisted storage.
• "name": <string>
• "description": <string>
• "start_location": <string> # the id of a location in the file
• "xp_monsters_per_level": <integer> # The engine uses a simplified experience scale. xp_monsters_per_level represents the number of monsters of equal level that it takes to level up. Fighting higher level monsters will give more experience, while lower level monsters will give less. An xp_monsters_per_level of 0 means no leveling up.
• "xp_difference_scale": <integer> # an integer percent for the bonus or penalty in experience gains per level difference. With an xp_difference_scale of 20, if you defeat a monster 3 levels higher, you will gain a 60% experience bonus. Leaving this out or setting it to 0 gives no bonus or penalty.
• "classes": <list> <string> # the ids of all allowed classes for the story. These must be valid battler ids.
• "opening_dialog": <string> # The identifier for a dialog to play whenever the game is reset.
• "win_dialog": <string> # The identifier for a dialog to play when the player finishes the game.
• "credits_dialog": <string> # The identifier for a dialog the story credits.
• "default_activity_tracking": <bool> # This determines whether paths default to activity tracking or not. Defaults to False
• "activity_threshold": <integer> # The number of active seconds per minute the player must maintain in order to count as active. Defaults to 30.
• "allow_respawn_on_death": <bool> # Whether to end the game, or automatically reload at the last respawn point on death. Defaults to False, meaning to end the game.
• "debug_variable": <string> # The name of the debug variable. This defaults to "debug" and can be turned on by setting #define PUBLISH to 0 in MiniAdventure.h
• "locations": <list> <location> # This is a list of location objects to which the player can travel
• "dungeons": <list> <dungeon> # A list of dungeons. At processing, each dungeon is turned into a list of locations.
• "skills": <list> <skill> # A list of the skills available to monsters int the story
• "battlers": <list> <battler> # A list of battlers available to the locations, and available as classes.
• "dialog": <list> <dialog> # A list of dialog available to events and the story itself
• "events": <list> <event> # A list of events that can be attached to locations, battlers and battle events
• "battle_events": <list> <battle_event> # A list of battle events that can be attached to battlers
• "key_items": <list> <key_item> # A list of key items which are names for game variables
• "external_files": <list> <string> # A list of filenames. Each json file should contain a list of named lists of anything that can normally be included in a story, such as "locations", "battlers", or "events"

##Location

• "id": <string> # unique identifier for the location. During processing, these are turned into indexes directly into the processed file.

• "name": <string>

• "menu_name": <string>

• "menu_description": <string>

• "adjacent_locations": <list> <string> # This is a list of location ids to which one can move from the given location. A location with a length bigger than 0, will only use the first two entries.

• "background_images": <list> <string> # This is a list of filenames for images that can be shown while traversing the location. For the moment, these files must already be included in the appinfo.json file.

• "length": <integer> # The number of minutes it takes to journey across the location. If this is zero, the player is simply given a menu of new locations to which to travel.

• "monsters": <list> <string> # These strings are ids for battlers included in the story. For a location with length, the chance of an encounter in any given minute are given by dungeon["encounter_chance"]. For a location with length == 0, a monster on the list will be encountered upon entering the location.

• "encounter_chance": <integer> # Determines the likelihood in any given minute of encountering a monster.

• "base_level": <integer> # Determines the level of monsters encountered in the location

• "location_properties": <string> # elements of a bit field that determine things that happen at the location. They come from g_location_properties at the top of process_stories.py.

  g_location_properties["rest_area"] = 1 << 0
g_location_properties["game_win"] = 1 << 1
g_location_properties["level_up"] = 1 << 2
g_location_propertires["respawn_point"] = 1 << 3

• "initial_event": <string> # Identifier for an event that determines whether this event is accessible from other locations. It also sets game state variables on arrival to the location

• "events": <list> <string> # A list of events the player can choose to interact with while at the location

• "use_activity_tracking": <integer> # Determine whether this path makes use of activity tracking. 0 is false, 1 is true, and 2 means to use the default for the story. Defaults to 2.

• "inactive_speed": <integer> # How many points of progress the player makes per minute of inactivity. Default is 1.

• "active_speed": <integer> # How many points of progress the player makes per minute of activity. Default is 1.

• "skip_encounters_if_active": <bool> # Whether monster encounters are skipped while the user is active. Requires the current path to "use_activity_tracking". Defaults to True.

• "grant_xp_for_skipped_encounters": <bool> # Determines whether the player is granted experience for skipped encounters as if they had defeated the monster. Defaults to False.

• "extend_path_during_activity": <bool> # Allows the designer to extend a path for as long as the player is active. This can prevent interruption where the user is notified of arriving at their destination before they are done being active. It can also allow for increased experience gain if "grant_xp_for_skipped_encounters" is true. Defaults to False.

##Dungeon

A dungeon will be unrolled into a series of locations. These locations alternate between paths with length > 0, and fixed locations with length == 0. The properties of the dungeon become the properties of the locations as appropriate.

• "id": <string> # unique identifier for the dungeon. When unrolled, the endpoints of the dungeon are locations with ids "id" + "_start" and "id" + "_end". These should be used by other locations to connect to the dungeon.
• "name": <string>
• "adjacent_locations": <list> <string> # These are location ids. Like a location with length > 0, a dungeon will only make use of the first two as the end points.
• "background_images": <list> <string> # As with locations, these are filenames for images. This is the list used for paths.
• "fixed_background_image": <list> <string> # The background image used for fixed locations between dungeon floors.
• "length": <integer> # The length of each dungeon floor
• "base_level": <integer> # The starting level of monsters in the dungeon
• "level_rate": <integer> # The number of floors after which the level of monsters will increase by one
• "encounter_chance": <integer> # The chance of an encounter on dungeon floors.
• "monsters": <list> <string> # The ids of the battlers to be seen in the dungeon. These will only show up on the floors with length > 0, and not on the fixed locations.
• "monster_scaling": <integer> # The number of floors between adding a new monster to the mix. If this is 0, all monsters are available on all floors.
• "use_activity_tracking": <integer> # Determine whether this dungeon's paths make use of activity tracking. 0 is false, 1 is true, and 2 means to use the default for the story. Defaults to 2.
• "inactive_speed": <integer> # How many points of progress the player makes per minute of inactivity. Default is 1.
• "active_speed": <integer> # How many points of progress the player makes per minute of activity. Default is 1.
• "skip_encounters_if_active": <bool> # Whether monster encounters are skipped while the user is active. Requires the current path to "use_activity_tracking". Defaults to True.
• "grant_xp_for_skipped_encounters": <bool> # Determines whether the player is granted experience for skipped encounters as if they had defeated the monster. Defaults to False.
• "extend_path_during_activity": <bool> # Allows the designer to extend a path for as long as the player is active. This can prevent interruption where the user is notified of arriving at their destination before they are done being active. It can also allow for increased experience gain if "grant_xp_for_skipped_encounters" is true. Defaults to False.

##Skill

• "id": <string> # unique identifier for the skill

• "name": <string>

• "description": <string>

• "type": <string> # Must be from the list g_skill_types at the top of process_stories.py. Will be turned into integers during processing. This determines how the skill behaves.

  g_skill_types["attack"] = 0
g_skill_types["heal"] = 1
g_skill_types["counter"] = 2
g_skill_types["buff"] = 3
g_skill_types["debuff"] = 4

• "speed": <integer> # How quickly the skill executes after being chosen.

• "damage_types": <list> <string> # These strings must be from g_damage_types at the top of process_stories.py. This will be turned into a bitfield during processing.

  g_damage_types["physical"] = 1 << 0
g_damage_types["magic"] = 1 << 1
g_damage_types["fire"] = 1 << 2
g_damage_types["ice"] = 1 << 3
g_damage_types["lightning"] = 1 << 4
g_damage_types["slashing"] = 1 << 5
g_damage_types["piercing"] = 1 << 6
g_damage_types["bludgeoning"] = 1 << 7
g_damage_types["holy"] = 1 << 8

• "potency": <integer> # How strong the skill is.

• "cooldown": <integer> # How many combat rounds must pass before the skill is ready to be used again

##Battler

• "id": <string> # unique identifier for the battler. This should be included in the monsters list of locations and dungeons. They can also be used as the classes for the player character.

• "name" <string>

• "description" <string>

• "image" <string> # The image used for the battler during combat. Must already by included in appinfo.json.

• "combatantclass": <dict> # This dict has keys from g_combatant_stats and values from g_combatant_ranks. All will be turned into integer values in processing

  g_combatant_stats = ["strength", "magic", "defense", "magic_defense", "speed", "health"]
g_combatant_ranks["rankf"] = 0
g_combatant_ranks["ranke"] = 1
g_combatant_ranks["rankd"] = 2
g_combatant_ranks["rankc"] = 3
g_combatant_ranks["rankb"] = 4
g_combatant_ranks["ranka"] = 5
g_combatant_ranks["ranks"] = 6

• "skill_list": <list> <skillentry> # Each skill entry must have the id of a skill that is defined in the file, as well as the minimum level for the monster to have access to it. This way more powerful monsters and players get access to a wider variety of skills.

• "event": <string> # An identifier for an event, which determines whether that monster can appear as an opponent. In addition, the event can change game states when the monster is defeated.

• "battle_events": <list> <string> # A list of Battle Events that can be active while in combat with the battler.

• "vulnerable": <list> <string> # damage types the battler takes extra damage from

• "resistant": <list> <string> # damage types the battler takes less damage from

• "immune": <list> <string> # damage types the battler takes no damage from

• "absorb": <list> <string> # damage types the battler heals from

• These all use the same values as skills' damage types:

  g_damage_types["physical"] = 1 << 0
g_damage_types["magic"] = 1 << 1
g_damage_types["fire"] = 1 << 2
g_damage_types["ice"] = 1 << 3
g_damage_types["lightning"] = 1 << 4
g_damage_types["slashing"] = 1 << 5
g_damage_types["piercing"] = 1 << 6
g_damage_types["bludgeoning"] = 1 << 7
g_damage_types["holy"] = 1 << 8

##Event

• "id": <string> # unique identifier used by other object types to link to events
• "dialog": <string> # A dialog to play when the event is triggered. This works for events in locations, but not for battlers.
• "positive_prerequisites": <list> <string> # A list of game state variables that are all required to be true for the event to appear.
• "negative_prerequisites": <list> <string> # A list of game state variables that are all required to be false for the event to appear.
• "positive_state_changes": <list> <string> # A list of game state variables that will be set to true when the event is triggered. If the event has a dialog with the "allow_cancel" field set to true, the player can cancel the dialog to stop the state changes from happening.
• "negative_state_changes": <list> <string> # A list of game state variables that will be set to false when the event is triggered. If the event has a dialog with the "allow_cancel" field set to true, the player can cancel the dialog to stop the state changes from happening.

Battle Events

• "id": <string> # unique identifier used by other object types to link to battle events

• "dialog": <string> # A dialog to play when the event is triggered.

• "battler_switch": <bool> # Whether to switch to a new battler when the event is triggered. This can be used to change the state of an enemy, or to generate sequential fights.

• "automatic": <bool> # Determines whether this event is in a list to be activated by the player, or happens automatically.

• "full_heal_on_switch": <bool> # Determines whether to fully heal the enemy on battler switch. For a single enemy changing state, you probably don't want a full heal, but if a new monster is logically replacing the old one, you might want the full heal.

• "sub_event": <string> # This is an event identifier which can be used to leverage the prerequisites and game state changes from a standard event.

• "prerequisites": <dictionary> <string>:<value> # This provides a list of prerequisites based on battle state. There are currently 3 supported prerequisite types:

  monster_health_below_percent

  player_health_below_percent

  time_above : This counts time ticks since the last battler initialization, so you can have two battlers swap back and forth every 10 time ticks if they each have a time_above of 10.

Dialog

• "id": <string> # The identifier to be used by events to trigger this dialog
• "name": <string> # The text that appears in the text box at the top of the string while the dialog is displayed.
• "text": <string> # The actual text of the dialog. This is drawn in a scrolling text box in the center of the screen.

Game State Variables

Game state variables are defined and used in events. The creator of a story does not need to make any kind of global list. Simply using a variable name in a prerequisite or state-change list will allocate a spot in the bit array for that variable. By default, each story is limited to 256 boolean variables.

Key Items

• "id": <string> # This is the id of the game state variable that represents this key item.
• "name": <string> # The name by which the key item will be referenced when the player activates the Key Item menu option.