Starward Rogue:XML - EntitySystem Definitions

Overview

These are not ships -- they're just guns or whatever. They're how a ship actually does something like shoot or trigger an ability, generally.

An example

<system name="PlayerDirected_Minigun"
	category="PlayerDirectedWeapon"
	is_player_main_weapon="true"
	shot_type="BulletPointedBlue"
	damage_type="Ballistic"
	attack_power="14"
	fire_rate="0.4"
	range_actual="500"
	shots_per_salvo="1"
	shot_speed="1200"
	flagship_ability_type="DirectFireWeapon"
	targeting_logic="Direct"
	image_name="MantaGun"
	quality_tier="0"
>
</system>

Attributes

Most Important General

• category (EntitySystemCategory)
• 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.
  • When you set this, they will use RuntimeData/Images/Systems/image_name
  • Use Invisible to have the system not visibly show on the entity (often a good idea).
• 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 Player subfolder inside the Systems folder.
  • To make sure that our system looks for an image in there, we just set image_folder=”Player” 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.
• is_destroyed_after_finite_uses (int, optional)
  • if a number > 0, then the system is gone after triggering that many times. Default 0.

General Player-Only Stuff

• is_toggleable (bool, optional), defaults_toggle_off (bool, optional, defaults true)
  • only for player energy-use systems, really; pressing the related only_fires_on_keybind (or release) keybind toggles the system on and off (if toggled off, the modifiers it applies to the parent entity, if any, no longer have effect)
• display_name (string, optional)
  • what the player sees when the game tries to tell them the name of this system
• description (string, optional)
  • similar to display_name, not necessarily used in all contexts that display_name is

Most Important Weapon Stuff

• attack_power (float)
  • how much damage this system's shots do
• fire_rate (float)
  • how many seconds it takes the system to reload after firing a salvo before it can fire again
  • NOTE! If you want this to go really fast, then for enemies you also need to set the cue_time lower.
• cue_time (float, optional, default 0.5)
  • the number of seconds this system (or the entity, if this is the only cue-time system on it) puts out a little yellow pulse "cue" before it actually fires.
  • only applies to enemies, and this effectively reduces the firing rate.
• range_actual (int, required unless there's a BulletPattern)
  • how far this system's shots can fly until they disappear.
  • Note: completely ignored if 1+ special_bullet_patterns are defined.
• range_to_live_mult (float, optional)
  • this system's shots live this much longer or shorter than its range implies. Only current usage is making the mine's self destruct "system" shots not go anywhere, via mult=0
• time_to_live (float, optional, default 10)
  • this system's shots expire after this long regardless of range or whatever. Does not apply to BulletPattern stuff
• shot_speed (int, optional, default 350)
  • how fast this system's shots go
• shot_type (GameEntity name)
• the name of the GameEntity data that should be used for the system's actual shots
• special_bullet_patterns (comma-delimited list of bullet_pattern names, optional)
• the names of the BulletPattern(s) this system can generate; if there's more than one a pattern is picked randomly from the list each time it needs one

Cosmetic Stuff

• sounds_on_shot_fired (comma-delimited strings list)
  • If this system fires a shot, or a shot pattern, then one of the sounds in the list will be played at random. Default "Shot_QuietTwoPart1,Shot_QuietTwoPart2".
• min_ms_between_shot_fired_sounds (int, optional)
  • Some systems fire salvos of shots rather frequently, and so normally a 50ms delay between invocations of their sound effects is imposed. For some shots you may want a larger delay, though (seriously that’s a rapid-fire shot, then), or in other cases you may wish for silence, in which case you can put -1 (since sounds_on_shot_fired has a default value). Default 50.
• shot_movement_particle (particle_pattern, optional)
  • shots emitted from this system emit this particle while moving
• screen_flash_seconds_on_use, screen_flash_seconds_on_shot_detonation (both bools, optional)
  • makes the screen go white instantly on use or shot detonation (respectively), then fade to normal over X seconds
• beam_particle (particle, optional) and beam_particle_distance_interval (int, optional)
  • makes the beam emit that particle at points X distance apart along its length

Player-Only Weapon Stuff

• flagship_ability_type (PlayerFlagshipAbilityType, optional)
  • basically this should either be DirectFireWeapon for player guns/abilities or left out
• salvo_spread_responds_to_player_direction (bool, optional)
  • this system's shots fan out like the old TLF "spreadfire" weapon; targeting the angle to the cursor and fanning out more or less depending on range to the cursor
• fires_one_shot_from_each_other_player_directed_system (bool, optional)
  • when this system fires, it actually fires one salvo per each of the player's main guns. This is used for the player's missile ability.
• charge_per_second, charge_cap, and charge_add_to_multiply_per_point (all float, optional)
  • only works in conjunction with only_fires_on_keybind (not the on_release version, since this is inherently on-release)
  • only works in conjunction with requires_item_type, as that tells it what resource to pull it from (presumably energy, but you could use missiles or credits if you wanted)
  • as you hold down the key, the system charges by that amount per second, up to the cap or how much you've got (whichever is less)
  • when you release the key, if the total charge < 1, it just doesn't fire or cost you any of the resource
  • when you release the key, if the total charge >= 1, it fires normally but with the attack power of all the shots will be multiplied by 1f + (charge * charge_add_to_multiply_per_point)
• shots_spawn_at_reticule (bool, optional)
  • makes the shot spawn at CalculateReticulePointForPlayerRightNow
  • if that's outside the room or in an indestructible within-room wall it tries to walk it back towards the player
• shots_instantly_hit_all_enemies, shots_instantly_hit_all_non_boss_enemies (both bool, optional)
  • both cause the shots emitted by that system to instantly hit all enemies and disappear (so the shots will generally not ever be seen); they apply all the normal on-hit logic, modifier transfer, etc
  • the second excludes any enemy where BossType != None
• instant_hit_all_includes_shootable_obstacles (bool)
  • works with shots_instantly_hit_all_enemies to also hit all shootable obstacles
• shots_follow_the_reticule (bool, optional)
  • shots emitted this system are basically glued to the cursor/reticule, moving instantly to that location even if it goes into a wall

Most Important Player-Item Stuff

• related_item (string, optional)
  • This is required on any systems that can be dropped by the player (ammo items and consumables, basically). This tells what icon to show in the bottom of the screen, as well as what system to actually drop.
• only_fires_on_keybind_release (KeyBind, optional)
  • the system only fires when the player presses and then releases this key; there's a ton of KeyBind values but the only one intended for this currently is ***HoldAndReleaseToFireMissile
• only_fires_on_keybind (KeyBind, optional)
  • the system only fires when the player presses this key (doesn't wait for release); the only KeyBind values intended for this currently are:
    • UseEnergyBasedSystem
    • UseConsumableSystem
• requires_item_type (InventoryItemType, optional)
  • the system cannot fire unless the player has a certain amount (requires_item_amount) of this item type (Missile, etc)
• requires_item_amount (float, optional)
  • the amount required by the previous flag's logic
  • you'll generally want to use int costs, but sometimes partial is necessary
• is_player_main_weapon (bool, optional)
  • use this if this is a "the player's two main guns" weapon; like the starting miniguns (or whatever) or ones that the player can pick up along the way. This is so the game can properly swap them in and out on pickup.
• disabled_if_zero_of_item (InventoryItemType, optional)
  • if you've got none of that resource left, the system is considered disabled
• consumes_all_required_item_on_use (bool, optional)
  • only works in conjunction with requires_item_type
  • after this system is used, all of that item is removed from the player's inventory (after whatever normal cost is associated)

Other Weapon Stuff

• ammo (int, optional)
  • how many shots until the system cannot fire anymore. Right now only used for consumables, with a max ammo of 1.
• shots_per_salvo (int)
  • how many shots the system fires at once. If used with a BulletPattern, generates that pattern that many times.
• one_shot_per_target (bool, optional)
  • if true, and shots_per_salvo > 1, will spread out its shots (not firing more than one at any target)
• forced_angle_offsets (comma-delimited list of floats, optional)
  • overriden by BulletPattern
  • the angles each shot in the salvo will travel at, relative to the angle to the target; useful for bursts without resorting to an all-up BulletPattern
  • you can use this with single-shot salvos, but if the angle is more than a degree or so that's basically "a gun that always misses"
• hits_all_intersecting_targets (bool, optional)
  • beam-weapon only (that is, the shot type has the insta_fire flag). Makes this system's shots apply their full damage to everything on the line.
• shot_destroys_other_shots (bool, optional)
  • this system's shots destroy enemy shots they touch during flight, but the system will not specifically try to target enemy shots
• intercepts_other_shots (bool, optional)
  • similar to shot_destroys_other_shots, but the system will intentionally target enemy shots
• shot_sticks_after_intercepting_another_shot (bool), shot_dies_after_intercepting_another_shot (bool)
  • normally intercepting a shot leaves the interceptor intact unless the other shot also destroys shots
  • with (sticks) the interceptor will remain, but will cease all normal movement
  • with (dies) the interceptor instantly dies, along with the thing it intercepted
• damage_type (DamageType)
• fires_salvos_sequentially (bool, optional)
  • overriden by BulletPattern
  • this system will fire each shot in its salvo a short delay after the previous shot. Useful for strings of bullets without resorting to an all-up BulletPattern
• shot_area_of_effect (int, optional)
  • this system's shots will damage everything (for full normal damage) within this distance of them when they're removed from the game
• aoe_hits_friendly_targets (bool, optional, defaults TRUE)
  • this system's shots will damage even friendly targets with aoe
• shot_is_not_stopped_by_hitting (bool, optional)
  • this shot passes through enemy ships, damaging them only once (even if they encounter them again later somehow), but able to damage more than one ship overall
• shots_are_homing (bool, optional)
  • this system's shots will curve around to fly towards the target point/ship
• shot_proximity_detonation_range (int, optional)
  • makes the ship die when a ship it could gets within X of a normal collision (so basically it's a collision check with X as an extra added into the range checks)
  • does not necessarily do on-hit logic to the thing triggering it; but it will check for aoe and only_fires_on_death systems
• system_to_attach_to_shot (system, optional)
  • whenever this system emits a shot, that shot spawns with one of the specified systems (allowing shots that fire other shots, or have on-death explosions that create bullet patterns, or whatever)
• shots_do_friendly_fire_after_time (float, optional)
  • so after one of its shots have been alive for X seconds, it can hit friendly stuff, and its aoe can hit friendly stuff (even if it doesn't have the friendly-fire aoe flag)
• shot_damage_per_second_from_touching (float, optional)
  • creates an implicit melee-range system that is added to any shots systems of that type fire
  • copies the EntitiesMyShotsHit modifiers (if any) from this system-type to that implicit melee system-type
• shots_rubber_band_to_starting_point (bool, optional)
  • now when the shot reaches the end of its range-to-live it doesn't scale out, it sets its destination point back to where it came from. When it reaches that point it then scales out
• shots_rubber_band_to_firing_system (bool, optional)
  • similar, but rubber-bands back to the current location of the firing system (even as that system moves)
• range_damage_scaling_floor, range_damage_scaling_ceiling (both float, optional) and range_damage_scaling_optimal_range (int, optional)
  • if the shot has traveled zero distance before the hit, it gets the floor multiplier
  • if the shot has traveled exactly the optimal distance when it hits, it gets the ceiling multiplier
  • if the shot has traveled >= 2 * optimal before the hit, it gets the floor multiplier
  • in the other cases, it linearly interpolates between the floor and ceiling
  • the multiplier is applied to the shot's attack power at the time it hits
• range_speed_scaling_floor, range_speed_scaling_ceiling (both float, optional), and range_speed_scaling_optimal_range (int, optional)
  • same deal, except it multiplies the shot's speed at each sim-step according to the range travelled thus far
• deflects_shots (bool, optional)
  • if a shot from this system collides with a hostile shot, it deflects that shot back on the opposite angle of its current travel
  • a shot cannot be deflected twice
• deflects_shots_as_friendly_fire (bool, optional)
  • same deal, but also makes those shots be able to hit targets friendly to it
• shots_knockback (int, optional)
  • ships hit by this are knocked back X distance units (if that would put them in a wall they don't go that far)
• shots_knockback_on_firing_ship_to_target_ship_angle and shots_knockback_on_shot_to_target_ship_angle" to system (both bool, optional)
  • overrides the default logic of "shots_knockback pushes back on the angle the shot is travelling in"
• shots_do_portion_of_current_health_as_damage (float, optional)
  • does X * the current hull health of the ship in damage, where X is between 0 and 1 (not 0 and 100; this is a multiplier, not a percent)
• do_parallel_salvo_with_spacing (int, optional)
  • overriden by BulletPattern
  • only meaningful if shots_per_salvo > 1
  • puts the first shot in the center like normal
  • puts the second shot at the specified distance to one side
  • puts the third shot at the specified distance to the other side
  • puts the fourth shot at twice the specified distance to the first side, and so on
• salvo_angle_difference (int, optional)
  • overriden by BulletPattern
  • only meaningful if shots_per_salvo > 1
  • the first shot has no change
  • the second shot gets angle + the specified amount (in degrees)
  • the third shot gets angle - the specified amount
  • the fourth shot gets angle + twice the specified amount, and so on
• inaccuracy_spread (int, optional)
  • makes each shot emitted from the system get a random angle offset from -x to +x degrees
• inaccuracy_is_by_salvo (bool, optional)
  • makes the previous apply to the salvo as a whole, not the individual shots
• miss_penalty_percent (int, optional)
  • if a shot expires without hitting any entity, it does this percent (expressed as 0 to 100) of its normal damage (whatever it would have done to an enemy at that time) to the ship which fired it
• spawns_entity (entity, optional)
  • when the system is triggered, an entity of this type is spawned at the location of the system
• hull_health_siphon_portion (float, optional)
  • whenever shots emitted by this system do damage, X% (expressed as 0 to 1) of the damage done is also applied as healing to the firing ship's hull
• shots_teleport_to_target_point (bool, optional)
  • whenever this system emits shots, those shots instantly teleport to the target point (whatever that is based on the system's targeting_logic and context)
• shot_gravity_pull_per_second, shot_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
• shot_gravity_affects_shots, shot_gravity_affects_friendlies (both bools, optional)
  • normally it only affects enemy ships; these change that
• shot_gravity_has_repelling_effect (bool, optional)
  • makes the shot's gravity pull do a repulsion instead
• drones_are_finite (bool), drones_are_guards (bool)
  • if has drones and fire_rate > 0, then every (fire_rate) seconds it picks a drone from this system's drone nodes
  • if finite, that "ball" is not returned to the random bag from which the drone type is picked; if there are no more items it just doesn't spawn more
  • if guards, the drones are spawned with FlockBehaviorType.Buddy and AIRelatedEntityID set to this system's parent ship
• distance_threshold_modifiers_applied_to_nearby_entities (int)
  • only works in conjunction with modifiers with target=NearbyEntities
  • each sim-step, this entity checks for other entities within (distance) and copies these modifiers to those entities
  • because of the frequency of copying, all these modifiers should probably have do_not_stack
  • combined with a short duration (say, half a second), this imitates an effect (like movement slowing) that only lasts while this entity is in range and for a short time after
• modifiers_applied_to_nearby_entities_can_target_allies (bool), modifiers_applied_to_nearby_entities_can_target_enemies (bool), modifiers_applied_to_nearby_entities_max_simultaneous_affected (int)
  • works in conjunction with target=NearbyEntities modifiers, targeting (allies|enemies), and if (max) > 0 it obeys that as well (preferring to keep affecting the ones it affected the previous check)

AI-Only Weapon Stuff

• targeting_logic (TargetingLogic)
• firing_timing (FiringTiming, required if Category == Weapon)
• range_do_not_fire_until (int, optional)
  • how close the system has to be to consider firing on a target
• range_chases_until_within (int, optional)
  • how close the AI of the system's parent entity will try to get (generally it only checks the first system for this)
• fires_from_any_range (bool, optional)
  • this system will consider targets out of range, and even fire at them
• destroys_firing_entity (bool, optional)
  • makes the entity that fired it go boom
• only_targets_damaged_ships (bool, optional)
  • only targets entities that have already been damaged
• only_targets_nearest_ship (bool, optional)
  • only targets the nearest eligible target; probably only meaningful for a player familiar
• only_fires_on_death (bool, optional)
  • used for self-destruct explosion "systems" like on the mines
• requires_line_of_sight_of_player_to_fire (bool, optional)
  • this system has to be able to see the player (not going through obstacles) to be able to fire
• line_of_sight_recalculation_interval (float, optional, default 0.2)
  • the most often (in seconds) this system will recompute l-o-s for the previous flag's logic
• targets_entity_that_last_damaged_my_entity (bool, optional)
  • after it fires a salvo, the remembered last-damaged-by is cleared
• shots_hitting_player_warp_responsible_entity_to_parent_entity (bool)
  • if a shot from this system hits the player, then the parent entity of this system is destroyed and the entity which spawned that parent entity (if any) instantly teleports to its location
• shots_steal_credits (float), credit_drop_on_death_portion (float)
  • if a shot from this system hits the player, the player loses (shots_steal_credits) credits
  • if the parent entity of this system dies, then (credit_drop_on_death_portion ) * the credits stolen by this system are dropped on the ground
• shots_die_instantly_at_boundary_direction (FourDirection), shots_die_instantly_at_boundary_distance_from_wall (int)
  • when shots from this system get within (distance) of the (direction) external room wall they instantly are removed from the game
• attack_power_against_player
  • if a shot from this system hits the player instead, it acts as if this were the base attack power instead of the normal attribute
  • defaults to whatever attack_power is
  • this is internally implemented as a multiplier, since the base attack power of a shot is factored into the computation before the shot hits, and thus before it knows whether or not it will hit the player; but for the purpose of editing the xml this is in the same units as attack_power, rather than a percent or multiplier
• shots_hit_friendlies_that_have_just_been_knocked_back (bool)
  • shots emitted by this system can hit friendlies that were knocked back in the past tenth of a second or so

Oddities For Specific Player Items

• energy_shield_damage_portion, energy_shield_conversion_multiplier (both float, optional)
  • the first is the percent of damage done to the parent entity that the conversion will try to apply to
  • the second is the cost in energy of each point of damage prevented, thus determining the max amount of damage that can actually be converted
• shot_disintegration_speed_mult (float, optional).
  • Normally shots decay and shrink down in both size and damage dealt when they pass the end of their range or lifespan. This gives them a nice fade-out, but also increases the range somewhat based on the speed of the shot.
  • This multiplier lets you make this process of decay happen faster (>1) or slower (<1). A multiplier of 6 or more will make it almost instant, but without jolting out of existing unprofessionally. Default 1.
• revives_parent_entity_with_hull_health_portion (float, optional)
  • whenever the parent system of this ship would normally die, its hull health is immediately set to X% (expressed as 0 to 1) of its max hull health
• reveals_entire_map (bool)
  • when this system is triggered, the map of the current floor is fully revealed
• reveals_room_types (List<RoomType>)
  • when this system is triggered, all rooms on the current floor of the specified types are revealed
• teleports_player_to_boss_room (bool)
  • when this system is triggered, if the player is not in the boss room, the player is teleported to a random door (not the one to the next floor) in the boss room.
• teleports_player_to_unvisited_room_of_type (RoomType), teleports_player_to_any_unvisited_room (bool)
  • when this system is triggered, if the current floor has any unrevealed rooms of this type (or any type, for the second field), the player is teleported to one (if none found, there's a chat log message)
  • if the new room is a secret room, any secret doors bordering the room are revealed
  • any locked doors bordering the room are unlocked
• teleports_player_to_next_floor (bool)
  • when this system is triggered, the player is teleported to the next floor
• scraps_and_regenerates_current_floor (bool)
  • when this system is triggered, the dungeon generates a new floor and replaces the current floor with it, then teleports the player to the beginning of the new floor
• converts_from_item_type (InventoryItemType), converts_to_item_type (InventoryItemType), item_conversion_ratio (float)
  • when this system is triggered, it converts the player's (from) inventory to (to), at (ratio), until either the from supply is exhausted or the to inventory is full
• makes_next_purchase_free (bool)
  • when this system is triggered, it sets a flag (which persists until dungeon exit or until you use it) that makes the next store purchase free
• item_refund_chance (int), item_refund_portion (float), item_refund_cooldown (float), item_refund_requires_kill (bool)
  • when a shot emitted from this system hits (or kills) a ship, there's a % (chance, 1 to 100) that (portion, 0 to 1) of the required_item_type cost is refunded to the player inventory
  • cannot happen more often than (cooldown, default 0.3), tracked independently per system
  • portion can be negative, in which case it actually charges you extra on-hit or on-kill, which might be useful for something that's supposed to have a low cost to try but a higher cost to succeed
  • this is mainly for weapons with required_item_type=Energy, but Credits could work too, for a kind of very short-lived mercenary attack
• shots_drift_towards_hostile_ships_range (int), shots_drift_towards_hostile_ships_speed (int)
  • shots fired by this system will move at (speed) towards hostile ships in (range), in addition to their normal movement
  • so not really homing, just kind of "magnetic"; whether it generates a collision depends a lot on the shot's speed and the magnetism strength
• authorizes_when_parent_hit_by_enemy (bool, default true), authorizes_when_parent_hit_by_friend (bool)
  • works with firing_timing=WhenParentEntityHit and hitbox.on_hit_triggers_systems_of_type; if the entity triggering the authorization does not pass these flags it doesn't actually authorize the activation

Spawning Stuff

• spawns_entity_ship_category (ShipCategory)
  • similar to spawns_entity, but randomly picks from entity types with a matching ship_category
• only_enabled_if_player_needs_missiles (bool)
  • if the player has any missiles, this system is disabled
  • if there are any missile pickups in the room, this system is disabled
  • if there are any enemies spawned by this system in the room, this system is disabled
  • if the room has already been won, this system is disabled
• entities_spawned_by_this_always_drop (entity)
  • any entities spawned by this system will always drop the specified entity type on death
• portion_attack_power_gain_per_my_portion_health_lost (float)
  • when this system emits a shos, the attack power of the shot is multiplied by 1 + (the portion of the system's parent entity health lost * this field)
  • so if this is 1, then as the parent entity's health approaches zero the attack power of newly emitted shots will approach twice what it would otherwise be
• spawns_familiars (List<GameEntityTypeData>)
  • when this system is triggered, it spawns each of the listed entity types as familiars for the system's parent entity (works for players or enemies; the player ones will normally persist between rooms)
• creates_x_item_pickups_nearby (int)
  • when this system is triggered, it spawns that many entities from ItemPool.RegularEnemyDrop near the player

Sub-Nodes

drone

specifies the entities that can spawn from this system; see drones_are_finite and drones_are_guards

Attributes:

• type (entity)
  • the type of entity to spawn
• count (int)
  • if drones are finite, this is the number of this type of entity that can be spawned from this system. Otherwise this is just the relative frequency at which this type of entity will be spawned from this system.

Starward Rogue XML Documentation Main