Starward Rogue:XML - GameEntity Definitions

Overview

A lot of these things cross over between any type of entity, and some things are specific to only certain entity types (ships only, or shots only). So we're going to break it out like that, with specific notes for each section as relevant.

An example

<entity name="Goldbug"
display_name="Goldbug"
    	behavior="Stationary" category="Ship"
    	speed="0" turning_resistance="2.25"
    	max_health="50"
    	image_folder="Enemy_Stationary"    
	>
	<system type="Goldbug" offset="0,0" />
	<hitbox radius="32" />
    	<stacked_image src="Attachments/TarraCrawlerArm" size="60" offset="-20,20" />
	<modifier target="MyShots" type="RicochetsOffTerrain"/>
</entity>

Note that the above is all one xml node (entity) with a bunch of attributes, until you get down to the end carat (>). Then the next line has a self-terminating hitbox node (self terminating means it does <hitbox/> rather than having <hitbox></hitbox> -- you self-terminate nodes if they don’t have any sub-nodes). There’s then a stacked_image node, and a modifier node, all of which are sub-nodes of the entity.

Attributes

These are things that go directly on the entity node, in the format attribute=”value”. So in the code <entity name="Goldbug">, name is the attribute and Goldbug is the value for that attribute.

Most Important General

• name (string)
  • All entities must have a name. The name for an entity must be absolutely unique from any other entities in the game, no matter what file they are in.
  • The name is actually more of a “primary key” identifier, and it’s not something players would ever see.
    • “SDT#$S” is a perfectly valid name if you want, although it’s a super unhelpful one so please don’t do it.
  • By default, the image for any entity is based on its name. This can (and often should be) overridden, however -- the image_name property does that.
    • Ships:
      • By default they will use the image RuntimeData/Images/Ships/yournamehere
    • ItemPickups:
      • By default they will use the image RuntimeData/Images/Items/yournamehere
    • Shots:
      • By default they will use the image RuntimeData/Images/Shots/yournamehere
      • It’s unlikely you will ever define a shot, however. You’ll define bullet patterns and systems and ships, but all a shot is is a graphic and a collision box. You’ll reference those, but not define them.
        • The systems and bullet patterns denote how shots move, what their damage is, speed is, etc, etc, etc.
    • Obstacles:
      • It’s really complicated how these use the images, and tends to be very tileset-dependent, which is not something in the purview of what you’re really designing here. That’s more to do with environment than enemies/items.
• category (GameEntityCategory)
  • Oi! What is this thing? Depending on what you say, it will be parsed differently.

Ship-Only Stuff

• display_name (string)
  • THIS is what the player sees as the “name of the ship.”
• acceleration (float)
  • How fast the ship moves from speed zero to its max speed. Does not impact deceleration speed. Default: insta-accelerates (0).
• min_ship_speed (int)
  • If the ship is accelerating from zero, what does it immediately jump to? If it's trying to move at all, what's the minimum speed it will go? The default is 20. For ships with low acceleration, setting this higher and then letting them accelerate more slowly to their max speed can be helpful.
• acceleration_for_momentum_mode (float)
  • like acceleration, but used instead of that number if (and only if) momentum mode is on and this is a player hull.
  • defaults to the normal acceleration value
• acceleration_for_sprint (float)
  • if this is a player hull and you are accelerating while still under your normal (non-sprinting) top speed, then this value gets added to your acceleration-of-relevance to boost you even faster.
  • once you are at a speed that is higher than your normal max speed -- aka you are in sprinting-only territory -- then this is your sole acceleration value.
  • defaults to the acceleration_for_momentum_mode value
• deceleration (float)
  • How quickly the ship will stop when it wants to stop. Most useful for player ships. Default: insta-decelerates (0).
• deceleration_for_momentum_mode (float)
  • like deceleration, but used instead of that number if (and only if) momentum mode is on and this is a player hull
  • defaults to the normal deceleration value
• deceleration_for_sprint (float)
  • if this is a player hull and you are trying to stop from a speed that is higher than your normal max speed -- aka you are in sprinting-only territory -- then this is your sole deceleration value. Once your speed is back down under your normal max speed, then the deceleration-of-relevance takes over again.
  • defaults to the deceleration_for_momentum_mode value
• speed (float)
  • What is the maximum speed this ship can move at? This is measured in pixels per second, or thereabouts.
• sprint_speed (float)
  • the alternate max speed used when sprinting (only matters for the player)
• max_shield (int)
  • How many shots can the ship completely block per room. Each shield point block one shot of any magnitude and then that block disappears.
• ship_category (ShipCategory)
  • Determines a lot about how the ship is seeded.
• time_to_visually_rotate_180_degrees (float, optional, default instant)
  • in seconds, the time it takes to do a complete 180 rotation when changing duration; smaller turns take proportionately less time
  • IMPORTANT NOTE: this is not actually a turning radius. If a ship decides to change direction of _movement_, it does so instantly. Otherwise it's way too easy to get irrevocably stuck on walls since ships have no "reverse gear". What this controls is how long it takes for the ship's rotation to "catch up" with its movement. This is not purely visual, as it impacts the position of the ship's hitboxes and systems (if any of them have offsets other than 0,0).
• time_to_rotate_firing_direction_180_degrees (float, default instant)
  • if > 0, the entity's effective "angle to reticule" does not update instantly but changes at this finite speed, expressed in the same terms as time_to_visually_rotate_180_degrees
• knockback_resistance (float)
  • The portion, as 0 to 1, of knockback that entities of this type should ignore. So 0 is no resistance (and default), 0.5 causes the entity to only be knocked back half as far, and >= 1 causes the entity to be immune to knockback. Incidentally, -1 would cause the entity to be knocked back twice as far, though long-distance knockback would be pretty weird since it's an instant location change.

AI-Only Ship Stuff

• rotates_to_face_firing_direction (bool)
  • Whenever the ship fires, the ship instantly faces the direction of the target Default: false
• passive_rotation_speed (float)
  • A passive rotation that happens over time, having nothing to do with movement. Default: false
• behavior (FlockBehaviorType)
  • Determines the way that the ship will act, at least to start off with (something could change that later in the life of the ship). Default: Attacker
• seeds_directly_in_rooms (bool)
  • Default true. If this is set to false, then the enemy will not naturally show up in the game! This is normally bad, right?
  • The main purpose of this is for multi-stage enemies. With those, when one enemy dies, it turns into another enemy type. If you don’t want that second enemy type showing up except via this process, then set this property to true.
  • TLDR: this is typically true on the later stages of enemies, but omitted everywhere else.
• damage_per_second_from_touching (float)
  • If a player is touching this ship, how much damage per second does that cause to the player? Default: 10.
• initial_movement_driving_bullet_pattern (bullet_pattern, optional)
  • the entity spawns with the logic from the first bullet node in this pattern
  • if the pattern has a die node that WILL kill the entity (instantly, no scaling out)
  • if the pattern has no die node and the pattern runs out of actions the ship will switch to normal non-bullet-pattern behavior
• teleportation_interval (float), teleportation_particle (particle_pattern), teleportation_invisible_time (float), teleportation_telegraph_time (float), teleportation_distance_from_player (int)
  • every (interval) seconds, assuming the entity isn't doing something strange (not doing bullet pattern movement, etc), the entity:
  • spawns (particle) at the origin
  • disappears for (invisible_time) seconds (its systems are also disabled for this time)
  • moves to a point (distance) from the player's current location
  • displays a telegraph animation at the destination for (telegraph_time) seconds
  • spawns (particle) at the destination
  • reappears
• teleports_at_health_portion_less_than_or_equal_to (float)
  • when the entity is first reduced below X% of max health (expressed from 0 to 1), it teleports using the particle, invisible, telegraph, and distance flags above
• cloaked_if_has_not_fired_within_last_x_seconds (float), cloaking_fade_time (float)
  • when the entity has not fired within last x seconds, it fades to invisibility over (fade_time) seconds
• cloaking_goes_partial_over_floor (bool), cloaking_goes_partial_over_window (bool), cloaking_partial_opacity_reduction (float), cloaking_full_to_partial_time (float)
  • when entity is cloaked and over (floor or window), it goes to (1f-partial_opacity_reduction) over (full_to_partial) seconds
• invincible_when_not_cueing (bool)
  • if this entity is not cueing a weapon at a given instant, it is immune to all damage at that instant
• spawning_patterns (List<bullet_pattern>)
  • when this entity is spawned by room-generation, instead of just spawning one at the center of the corresponding tile, it picks one of the bullet patterns in this list, then spawns one entity per bullet node that's a direct child of the pattern (so child nodes that do their own spawns don't count)
• on_death_drops_ability_points (int)
  • the number of ability points this entity drops when it dies
  • the default values are set by the ShipCategory of the enemy. Extra-tough (or weak) enemies in each category should have their values adjusted.

Familiar-Only Ship Stuff

• familiar_type (FamiliarType)
  • For familiars that hang out around the player (or behave like normal ships, if set that way), there are different movement patterns that they can use. Default: None.
• is_familiar_that_dies_when_parent_dies (bool)
  • an entity with this flag without an entity that it is a familiar to instantly dies
• on_grant_restores_master_entity_shields (bool)
  • when this is initially granted to the player as a familiar, the player's shields are restored to full
• dies_if_master_entity_leaves_room (bool)
  • when the player changes room, and the player has this as a familiar type, this entity type will not spawn (normally all familiars are re-generated when you change rooms)
• familiar_regenerates_after_current_room (bool, default true), familiar_regenerates_after_current_floor (bool)
  • if neither of these are set, and this entity is a player familiar, the familiar is gone permanently if it dies
  • if (room) is set, it does the normal behavior of the familiar respawning every room change
  • if (floor) is set, it stops respawning normally until the next floor switch
• dies_if_master_entity_has_no_shields (bool)
  • if this has no master entity (that is, it's a familiar to that entity) or the master entity's current shield strength is zero, this entity dies

Unusual Ship-Only Stuff

• strafing_time (float)
  • If this is set, then every time the ship fires, it loses the ability to steer for this amount of time, and will just continue on at max speed during that interval. Default 0.
  • This was used a lot in TLF for ships that would do “strafing runs” past the player and then would wheel around in a slow arc and come back. But because the slow-arc style of ship movement is not in SR (because walls), this doesn’t really make as much sense conceptually.
    • Could still be interesting, though, for making an enemy that goes zipping past you while firing, and then has to regroup and turn back around. Would probably only work well with systems on the ship that fire when they have line of sight on the player or else this ship might just always be going nuts.
  • This is really useful if you want to have an invisible, invincible ship that does something like spawn enemies. Though honestly, this is a relic from TLF where stuff spawned offscreen from out of empty space, and here it would probably make more sense to have a visible spawner.
• never_stops_shots (bool)
  • Funky! Rather than shots hitting this and dying, any shots that hit it stay alive and just keep moving. Default false..
• always_faces_player (bool)
  • Creepily face the player at all times, regardless of movement. Default false.
• always_faces_firing_direction (bool)
  • Always face the direction it’s shooting, not moving. Default false.
• stun_resistance (float, optional)
  • any MovementSpeed modifiers copied to an entity with this, with either a negative Add or a < 1 Multiply, have their duration (if it's > 0) multiplied by 1f - this resistance value.
• death_spiral_movement_driving_bullet_pattern (bullet_pattern, optional)
  • the entity is incapable of dying normally
  • when the enemy would normally die, it instead switches to this pattern
  • the pattern needs a die node, and that will kill it; otherwise it will never die
• wake_range
  • used in conjunction with duration=UntilWoken modifiers. When the player ship gets this close AND this shiphas line of sight to the player, then it will wake up.
• wakes_on_shot
  • used in conjunction with duration=UntilWoken modifiers. When this ship gets shot, then it will wake up.

Cosmetic Stuff

• never_renders (bool)
  • The entity is… invisible? Default false.
• image_name (string)
  • Normally the name of the entity is what is used to find the image for the entity. This lets you override that logic.
  • The two particularly-relevant cases:
    • Ships:
      • When you set this, they will use RuntimeData/Images/Ships/image_name
    • ItemPickups:
      • When you set this, they will use RuntimeData/Images/Items/image_name
• image_folder (string)
  • This can be used with or without image_name. Often it is used without image_name.
  • For organizational purposes, it’s nice to be able to put graphics into arbitrary subfolders. So for instance, we have an Enemy_Bosses subfolder inside the Ships folder.
  • To make sure that our entity looks for an image in there, we just set image_folder=”Enemy_Bosses” and that’s it.
  • You can do folders-in-folders if you want, too, and then have a forward slash (/) separating those out.
    • Make sure to always use forward slashes when referencing filenames. If you’re working on windows it will work with a backslash, but then someone running this on osx or linux will have it fail.
• animator_frames (int), animator_sprite_dict_size (int), animator_speed (int)
  • if the filename designated by image_folder and image_name (which may be default values) plus "_Dict" as a suffix exists, image_name will be loaded as an animator with the corresponding (dict_size), (frames), and (speed).
• description (string)
  • We’re not really using this much for ships. But for ship hulls, we can use this to give players a description of what the pros and cons of that ship hull is. Overall ignore.
  • Also not used on most item pickups, because in their case the system that they are granting should instead have the description.
• sounds_on_takes_damage (comma-delimited strings list)
  • If this entity takes damage from a shot hitting it, then one of the sounds in the list will be played at random.
  • Default when a GameEntityCategory.Ship: "EnemyHit_DullThud1,EnemyHit_DullThud2"
  • Default when a GameEntityCategory.Obstacle or GameEntityCategory.StationaryObject: "ObstacleHit1,ObstacleHit2,ObstacleHit3,ObstacleHit4,ObstacleHit5"
• sounds_on_death (comma-delimited strings list)
  • If this entity dies, then one of the sounds in the list will be played at random.
  • Default when a GameEntityCategory.Ship: "EnemyDeath_Small1,EnemyDeath_Small2"
  • Default when a GameEntityCategory.Obstacle or GameEntityCategory.StationaryObject: "ObstacleDeath_Slap1,ObstacleDeath_Slap2,ObstacleDeath_Slap3"
• shader (ShaderType)
  • The type of shader that will be used to draw the entity. Generally you’ll want to use Normal, but Additive can be quite interesting also.
• particle_on_death (particle_pattern, optional)
  • this ship emits this particle when dying
• movement_particle (particle_pattern, optional)
  • this ship emits this particle while moving
• exhaust_offset (int)
  • This is an int that defines how far forward or backward the exhaust is from the ship. Default 0.
• death_throes_particle
  • when this entity is in death throes, it emits this particle
• death_throes_fade_to_black_time
  • when this entity is in its death throes, over this period of time it will fade to black
• draws_below_others (bool)
  • Does this ship draw below all other ships? Aka, the others can pass over it in all cases? There’s basically two layers of ships, anyhow, and this says “go to the bottom one.”
  • This is most useful for shots, saying that these are drawing on the floor under ships rather than above them. Great for ground sludge, etc.
• draws_as_floor_obstacle (bool)
  • Floor things that sit on the floor, like teleporter pads and pedestals, set this to true so that they will draw really low. Default false.
• override_mode_color (Color)
  • overrides the normal logic for determining the diffuse applied to the "mode" image of entities of this type. The mode image pulses in intensity, can be used for running lights, etc.
• is_considered_ground_walker (bool)
  • For ships that are actually walking on the ground (like mechs) rather than hovering, this should be true. Disables their little hover movement.
• invincible_while_in_same_room_with (List<entity>)
  • while any entity type in this list is present in the room, entities of this type are invincible
• invincibility_non_sim_special_bullet_patterns (List<bullet_pattern>)
  • while this entity is invincible, for any reason, it emits this non-sim bullet pattern

Any Type Of GameEntity Stuff

• max_health (int)
  • How much health does this thing have?
    • For the player, each box in the health bar is 2 health points. So 1 damage is half a block, 2 is a whole block, etc.
  • For enemies, they have VASTLY larger amounts of health, and the player does more damage, too. Average enemy healths might be more like 100 early in the game, whereas an equivalent player health might be 6.
    • The reason for this is based around how players can hit enemies repeatedly and there’s no break between when the player can hit them, versus the players are immune to damage for a short while after taking a hit (during the period of the red flash of showing damage).
• flies_through_obstacles (bool)
  • Is this thing able to move straight through non-wall obstacles? Default false.
• wall_collision_reduction (int)
  • If you are looking at the collision data for entities (hit F7), you’ll notice that the red circles are the hitboxes where the entity collides with other entities.
  • But the big blue square box is what it uses in order to collide with walls, because of the nature of rotating multiple circular hitboxes and so on. The blue box is “pessimistic” in order to make sure that it doesn’t look like the enemy is clipping into walls normally, but sometimes it can be too pessimistic.
  • TLDR: if you want to shrink that blue box, then you can use a positive integer here. Default 0.
• immune_to_all_damage (bool)
  • I’m invincible! ...You’re a looney. Default false
• on_death_ability_explosion_radius (int)
  • When I die, how big of a shot-clearing explosion do I make? Default 0.
  • Note that this does not hurt entities except for clearing shots it touches.
• periodic_movement_mode_interval_min (float)
  • If there is one or more periodic movement modes assigned to this entity (via sub-nodes), then what is the minimum interval of time (in seconds) between invocations of one of those modes? Note that during a mode being active, it won’t cause this to count down. Default 0.
• periodic_movement_mode_interval_max (float)
  • Same deal as above, but this is the max interval between choosing the modes. It does rand(min,max) as you might expect.
• on_death_transforms_into (string)
  • When this thing dies, does it instead turn into something else? For multi-stage enemies or obstacles, this is how you go from one stage to the next. The string here should be the name of the other entity. Default blank.
• familiars (comma-delimited strings list)
  • This is the list of entity names in the format “name1,name2” and so on of any familiars the ship might have by default. Most will not have any, but some enemies might have some built in. Who knows!
• starting_angle (int, optional)
  • all entities of this type will start with this angle when seeded, rather than picking a random angle like normal
• never_changes_angle_after_spawn (bool, optional)
  • quite aggressively prevents any change to the rotation of all entities of this type; they can still move on whatever angle, but the ship's visual rotation (and thus the offsets of hitboxes and systems on that ship) won't change.

Unusual Stuff For Any Type Of GameEntity

• gravity_pull_per_second, gravity_falloff_per_unit_distance (both floats, optional)
  • so if you had values of 100 and 0.2, then it would exert a pull on something up to 500 units away, where that pull is 20 at 400 distance, 40 at 300, 60 at 200, 80 at 100, etc
• gravity_affects_shots, gravity_affects_ships , shot_gravity_affects_friendlies (all bools, optional)
  • you need to set either shots or ships for it to do anything; always affects enemies, but only friendlies if you set that flag
• gravity_has_repelling_effect (bool, optional)
  • makes the entity's gravity pull do a repulsion instead
• special_object_type (SpecialObjectType)
  • I’m not even going to really fully define this here, because it’s something that is used on special-casey obstacles and not something that you’d really mess with directly much. Default None.
• dies_if_origin_system_is_disabled (bool)
  • if this entity was not generated by a system, or if that system's parent entity has died, or if that system is currently disabled for any reason (including toggling), this entity dies
• transforms_into_item_pickup_on_boss_room_win (ItemPool)
  • when this is in a boss room that has been one, an item from this pool is created at this entity's location and this entity dies

ItemPickup-Only Stuff

• credit_cost (int)
  • required if item_pools contains Shop
• on_pickup_grants_ship_system (string, optional)
  • when the player picks this up then the game finds the EntitySystem with this name and gives it to the player (swapping out the old system of that type, if any, and putting it on the ground)
• on_pickup_grants_familiar (string, optional)
  • very similar to on_pickup_grants_ship_system, but instead finds the GameEntity with name==this and grants it as an familiar to the player.
• on_pickup_grants_item (InventoryItemType)
• on_pickup_grants_health (bool)
  • When this thing dies, does it give health to the player? Default: false
• on_pickup_grants_amount (int)
  • Used with several other on_pickup properties. Default 0.
  • With on_pickup_grants_health: this specifies how much health the player gets.
• auto_pickup (bool)
  • When the player steps on this item, does it automatically go into their inventory? Default false
• item_pools (list of ItemPool -- required)
• frequency_in_item_pools (int, default 100)
  • If this is set to more than 100, then it will show up with greater frequency than it otherwise would -- 200 would mean twice as often as it otherwise would.
  • Similarly, 50 means half as often as usual, and 1 is 1% as often as usual.
• is_harmful_mysterious_circuit (bool), is_helpful_mysterious_circuit (bool)
  • use at most one or the other for a specific entity
  • this pickup is considered a mysterious circuit for the special logic of that concept
  • When a run is started, the game picks (difficulty.NumberOfNegativeMysteriousCircuits) negative circuits at random, and then picks enough positive circuits at random to bring the circuit total up to 10
  • It then randomizes the order
  • It doesn't load a base image; instead it gets an image from Images/Items/MysteriousCircuits
    • This will be consistent within a given run (unless the contents of that image directory are modified between save and load), but different on other runs
  • the first 4 out of the 10 (post randomization) are marked as known
  • unknown ones just show ??? for name and description
  • picking one up marks it known
    • and gives you a popup with its name and description
• should_be_remembered_as_power_up (bool)
  • the game will remember that the player picked up this power-up, for the remainder of the run
  • this remembering has no direct effects (that was already possible via modifiers with target=OnPickupGrantToPlayer and the like), it's just for record-keeping
• destroys_system_in_slot (SystemSlotType)
  • when you pick this up it destroys whatever was in the specified slot
• can_only_be_picked_up_if_you_have_a_system_in_slot (SystemSlotType)
  • if the player does not have a system in this slot, the player cannot pick up this item
• can_seed_multiple_times_per_floor (bool), can_seed_multiple_times_per_run (bool)
  • normally an item pickup won't be seeded if it's already been seeded this run; the (run) flag makes it do so. The (floor) flag also makes it do that, but also allows it to seed more than once per floor.
• do_not_seed_until_unlocked_with_x_ability_points (int)
  • for item pickups, tells the game not to seed it unless it has been unlocked with AP, and specifies the cost
• can_be_purchased_with_x_ability_points (int)
  • for item pickups, tells the game the player can purchase one of these at the beginning of a run by spending this many AP
  • randomly offers up to three items that have been unlocked or do not need to be unlocked, and that the player has the AP for

Seed-Limiting Stuff

For items and monsters and even obstacles, there may be restrictions on when we want them to seed. We may simply not be ready to have the entity as part of the game yet, but we want to be able to test it. Or we may want the player to have gone through whatever prior conditions in order to unlock this monster or item so that it starts appearing.

• is_not_ready_to_seed (bool)
  • prevents normal seeding of this entity type
  • does not apply to test chamber or tutorials (same goes for the rest of these do_not_seed flags)
• do_not_seed_unless_have_killed (entity), do_not_seed_unless_have_killed_count (int)
  • prevents normal seeding of this entity type unless the player has killed at least (count) of the specified entity type.
  • This is particularly useful for gating more difficult versions of enemies behind weaker versions. You have to kill a certain amount of the weaker version before the harder one starts getting mixed in, for instance.
• do_not_seed_if_have_killed (entity), do_not_seed_if_have_killed_count (int)
  • prevents normal seeding of this entity type if the player has killed at least (count) of the specified entity type.
  • This is useful for phasing out easier versions of enemies if they are just trivial past a certain point and you only want to keep the upgraded version.
  • Best advice is to make some overlap at the very least, so you have both the weaker and stronger version for a while before the weaker version gets phased out.
    • Transitions are nice, and a mixture of them can actually be more trouble than just a harder version.
    • So in some cases consider not phasing out weaker versions at all.
• do_not_seed_in_other_pools_until_picked_up_at_least_once (ItemPool)
  • prevents normal seeding of this entity type except for the specified ItemPool, until it has been picked up once
• do_not_seed_until_have_won_x_runs (int)
  • prevents normal seeding of this entity type until the player has won (x) runs
  • You can infer if the player has beaten the regular FinalBoss a certain number of times simply by looking at this.
    • For the SuperFinalBoss, look at this and mentally subtract 10 -- the first 10 runs won won't include the SuperFinalBoss.
  • At any rate, this is useful for gating certain things behind the concept of "win a few runs and then things shift more dramatically."
    • More specifically, this is a great way to introduce whole new enemy TYPES, rather than just harder versions of existing enemies.
• do_not_seed_if_have_won_x_runs (int)
  • prevents normal seeding of this entity type if the player has won (x) or more runs
  • You can use this to phase out a weaker enemy type if you so desire after the player has played a certain amount of time.
    • The general idea is that you can make the density of nasty stuff higher by introducing harder types of enemies and phasing out the weaker types of enemies if you want.
    • Best advice is not to really do this too much, but it is useful sometimes. Even weak enemies have their place.
• do_not_seed_until_x_floors_down (int)
  • prevents normal seeding of this entity type unless the player is currently on floor (x) or greater of the current run
  • so if you set this to 1 it won't do anything, but if you set it to 2 it will prevent the thing from seeding normally on the first floor of any dungeon
• do_not_seed_if_x_floors_down (int)
  • prevents normal seeding of this entity type if the player is currently on floor (x) or greater of the current run
  • so if you set this to 1 it won't ever seed, but if you set it to 2 it will prevent the thing from seeding after the first floor of any dungeon
  • This is actually super useful! If you're introducing lots of harder enemies the further down you go into a dungeon, you probably also want to start phasing out weaker ones. Gives more of a sense of increasing danger and unfamiliarity the further down you go.
• do_not_seed_until_unlocked_with_x_ability_points (AbilityPointCost)
  • prevents any seeding at all until the player has bought this item in the first-floor starting room with some ability points acquired on previous runs.
  • this item will show up randomly in the starting player room on the first floor if the player has at least >= this many ability points when starting the run, and the player can unlock and use the item then.
• can_be_purchased_with_x_ability_points (AbilityPointCost)
  • this doesn't actually prevent any seeding, but it seems to fit here.
  • this causes the item to show up in the first-floor starting room for purchase at this price if it has already been unlocked.
  • by default, if do_not_seed_until_unlocked_with_x_ability_points has been set, then this will be half of that value.
  • if do_not_seed_until_unlocked_with_x_ability_points is not set, but this variable is, then this item doesn't have to be unlocked but can still be bought at the start of a run.
    • In those circumstances we want to mainly focus on things that the player would find interesting and useful for sure. No need to put this on every item by any stretch.

Sub-Nodes

Until now, everything has been talking about attributes right on the entity node itself (so <entity attribute=”data”></entity>). Now we’re going to talk about sub-nodes that go inside the entity object, though.

An Example

From this example, there are four sub-nodes: one hitbox, two stacked_images, and one modifier.

<entity name="Goldbug"
display_name="Goldbug"
    	behavior="Stationary" category="Ship"
    	speed="0" turning_resistance="2.25"
    	max_health="50"
    	image_folder="Enemy_Stationary"    
	>
	<system type="Goldbug" offset="0,0" />
	<hitbox radius="32" />
 <stacked_image src="Attachments/TarraCrawlerArm" size="60" offset="-20,20" />    	
<stacked_image src="Attachments/TarraCrawlerArm" size="60" offset="20,20"/>
	<modifier target="MyShots" type="RicochetsOffTerrain"/>
</entity>

A key thing to note about all of these sub-nodes is that they in turn also have attributes of their own. Another key thing to note is that you can have as many copies of these kinds of sub-nodes inside an entity as you want. Aka, you can have 1 hitbox or 10, as needed.

system (default schema)

Overall premise: a system attached to this ship, that can actually do something like shoot or trigger a player ability or whatever. These have locations inside the sim, but cannot collide with anything, have no concept of health, etc.

Example:

<system type="Minigun" offset="20,10" />

Attributes

• type (EntitySystem name)
  • This tells it what system node to pull from the EntitySystem xml
• offset (int,int)
  • This is the x,y offset of the center of the system from the center of the entity. Particularly useful when you have many systems on a single enemy.
• add_degrees_to_shots (float)
  • The shots emitted from this system actually come out with the extra amount of this angle.

system (alternate schema for when you want random variation in enemies)

Example:

<system offset="20,10">
	<possibility type="Minigun" chance="3" />
	<possibility type="TestWeapon" chance="1" />
</system>

possibility Attributes

• chance (int)
  • the relative chance of that system being picked for that spot for each entity of this type being spawned
  • So in this example, it has a 3-out-of-4 chance of picking minigun, and a 1-out-of-4 chance of picking TestWeapon
  • Don't use on player hulls or familiars, or it will reroll every time you enter a new room

hitbox

Overall premise: this is a circular space that a ship can be shot in, or that a shot occupies and thus collides with ships via. It’s the part of the ship/shot/whatever that is “solid,” in most respects.

Attributes

• radius (int)
  • This defines the radius of the red circle of the hitbox (hit F7 to see that).
• offset (int,int)
  • This is the x,y offset of the center of the hitbox from the center of the entity. Particularly useful when you have many hitboxes on a single enemy.
  • Note that the pessimistic blue bounding box for hitting walls will encompass all the hitboxes you define.
• incoming_damage_multiplier (float)
  • a shot hitting this particular hitbox will have its damage multiplied by this before it's applied to the entity
  • set to zero for immunity to damage
    • negative numbers act like zero; they don't cause healing
• on_hit_triggers_systems_of_type (system)
  • a shot hitting this particular hitbox will authorize this system to fire (only matters if it's got firing_timing=Never)

stacked_image

Overall premise: sometimes we want to show multiple images on top of the base image of the ship or shot or what have you. This lets us build up larger ships than we’d otherwise have, and it lets us take off pieces when we move to “later stage” copies of the ship (just remove the stacked_image entries and hitbox entries of relevance when doing that.)

Attributes

• src (string)
  • This looks in the same folder that the base image of the entity is in, whatever that is. Generally speaking it’s nice to put the attachments in some sort of subfolder, and you can specify that all in this one field (as noted in the example above).
• size (int)
  • What is the width (and height) of this square image? I’m honestly not positive why we care, but do set it accurately just in case.
• offset (int,int)
  • This is the x,y offset of the center of the stacked image from the center of the entity. You’re presumably always going to want to set this to something.
• rotation (int)
  • The number of degrees (0 to 364) that the image should be rotated from the basic orientation of the entity it is stacked on. Default 0.
• flipX (bool)
  • Should we flip this horizontally? This is different from doing a rotation of 180, since this will keep it upright and mirrored rather than being upside-down.
• flipY (bool)
  • Same as flipX, but in the vertical axis instead.
• animator_frames (int), animator_sprite_dict_size (int), animator_speed (int)
  • if (dict_size) > 0, src (plus "_Dict" as a suffix) will be loaded as an animator with the corresponding (dict_size), (frames), and (speed)
• rotates_to_face_firing_direction (bool)
  • draws the stacked image with angle set to the "firing direction" of the parent entity, which is in turn moderated by firing_direction_rotation_speed if that's set on the entity
• draws_under_ship (bool)
  • draws the stacked image at a lower draw layer than normal
• animation_is_proportional_to_movement_under_power (bool)
  • if this is an animated stacked image, its animation speed is multiplied by the parent entity's current powered velocity / its max speed (max 1, min 0)
  • if the parent is not moving under its own power, the animation stops

• only_shows_if_ship_health_is_above_percent (float)
  • this image only draws if the health of the ship it is on is above the specified percent (in the format 0-1f)
• only_shows_if_ship_health_is_below_percent (float)
  • this image only draws if the health of the ship it is on is below the specified percent (in the format 0-1f)
• only_shows_if_ship_has_shields (bool)
  • this image only draws if the ship it is on has any shields at present.
• only_shows_if_ship_has_no_shields (bool)
  • this image only draws if the ship it is on has no shields at present.

Sub-sub node: frame_info

• frame (int)
  • which frame this applies to, where 0 is the first frame
  • if the animator doesn't have this many frames, this frame_info node has no impact
• possible_non_sim_patterns (List<bullet_pattern>)
  • when this frame is reached one item is picked from this list and triggered
• possible_sounds (List<string>)
  • when this frame is reached one item is picked from this list and played

room

Only used for bosses, basically for boss rooms rather than picking a room of that type and then populating it, it picks a boss of the appropriate type (miniboss or boss) and then tries to pick a room that will fit the boss. The rooms that will fit are specified as room sub-nodes on the boss's entity record, like this:

Example:

<room src="Boss/CMP_BossNoWindows" buddies="SmallEnemy,SmallEnemy" />

Attributes

• src (string)
  • the name of the room script to use, relative to RuntimeData/Rooms/ , and without the .txt extension.
  • the room script must contain a B to seed the boss at, or it will throw an error during seeding
• buddies (list of GameEntity names, optional)
  • the names of other monsters to seed with this specific setup (you can have more than one room node with the same src, and different buddy lists), at the 'U' tiles in the room script
    • if the room script's number of 'U' tiles is not exactly equal to the number of buddies specified here, it will throw an error during seeding

periodic_movement_mode

This is a large enough subject that it is defined here in its own section: Starward_Rogue:XML - PeriodicMovementModeType Definitions

Starward Rogue XML Documentation Main