[REFERENCE] Unit Blueprints

Discussion in 'Mod Discussions' started by Raevn, June 9, 2013.

  1. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Unit Blueprints
    Alpha Disclaimer: This information is still being compiled, but is currently based on PA Build 50256 and may change
    See PA Modding Changes for any changes that may have been made after this build.


    Units in PA are defined in .json files. Each unit has it's own folder, which is located in /PA/media/pa/units/<sub-folder>/<unit name>.

    All available units are listed in the file PA\media\pa\units\unit_list.json. The unit must be in this list for it to be present in-game.

    Viewing the .json files can be difficult due to the formatting, but using a json parser can help, such as JSONLint, or see this thread for a tool to re-format all .json files.

    As an example, below is the .json file for the Ant - named tank_light_laser.json in the data files, (renamed to .txt in order to upload):


    Client-Side/Server-Side attributes
    While the Unit blueprints can be edited freely, the Planetary annihilation server ultimately dictates most of the units attributes. This means most attributes effectively cannot be changed. Some are only for the benefit of the client (such as "display_name"), and these can be modified freely. Many attributes marked "Server Only" wont have any material effect on the game if changed, but can be altered to change the visual appearance of the client. These include content such as models and textures.

    Server Only attributes are marked in Blue.
    (Assumed) Client-Side attributes are marked in Green

    Attributes
    General
    Below is a list of attributes for units. Not all units will have all of these; any missing values may inherit from a base class (see base_spec)

    "audio": See Audio section, below.
    "base_spec": String. File path to inherited blueprint. Any values not present in a blueprint will use the values in the blueprint defined in base_spec (See [REFERENCE] Unit Blueprint Inheritance).
    "build_metal_cost": Integer. The metal cost of the unit.
    "buildable_types": String. Defines what units this unit can build. This is specified by combining unit types (without the UNITTYPE_ prefix) with & (and) and | (or) to logically allow/disallow construction. For example, the fabrication bot has the following:
    Code:
    "Land & Structure & Tech1 | Factory & Tech1 | Factory & Tech2 & Bot & Land"
    This lets it build units that have the Land, Structure AND Tech1 types, OR the Factory AND Tech1 types, OR the Factory, Tech2, Bot AND land types.
    "building_skirt": 2D Array(Integers). Defines the length and width of a building.
    "command_caps": Array (Strings). Defines what commands this unit has. Accepted values (leading "ORDER_" is optional):
    • "ORDER_Assist"
    • "ORDER_Attack"
    • "ORDER_Build"
    • "ORDER_FactoryBuild"
    • "ORDER_Move"
    • "ORDER_Patrol"
    • "ORDER_Reclaim"
    • "ORDER_Repair"
    "consumption": -> "energy": Integer. Ongoing energy usage of the unit.
    "consumption": -> "metal": Integer. Ongoing metal usage of the unit.
    "death": See Death section, below.
    "description": String. The description of the unit in-game
    "display_group": Integer. Determines the order this unit will appear in build menus (Higher numbers first).
    "display_index": Integer. Determines the display order of strategic icons (Icons with higher numbers will appear above lower ones)
    "display_name": String. The name of the unit in-game.
    "events": See Events section, below.
    "fx_offsets": See FX Offsets section, below.
    "guard_radius": Integer. The radius the unit uses for acquiring targets. The unit will use it's max weapon range instead if it is larger.
    "guard_layer": String. The layer on which the unit will attempt to look for targets. Accepted values:
    • "WL_Air"
    • "WL_AnySurface"
    • "WL_Land"
    "headlights": See Headlights section, below.
    "max_health": Integer. The health of the unit.
    "mesh_bounds": TODO
    "model": See Model section, below.
    "navigation": See Navigation section, below.
    "physics": See Physics section, below.
    "placement_size: 2D Array(Integers). Defines the length and width of a building footprint[/color]
    "production": -> "energy": Integer. How much energy the unit produces.
    "production": -> "metal": Integer. How much metal the unit produces.
    "recon": See Recon section, below.
    "storage": -> "energy": Integer. How much energy storage the unit has.
    "storage": -> "metal": Integer. How much metal storage the unit has.
    "TEMP_texelinfo": Float. See this post.
    "tools": See Tools section, below.
    "si_name": String. An alternate name to use when performing a Strategic Icon lookup (See [REFERENCE] Strategic Icons & Build Pictures).
    "unit_name": String. Internal unit name. Unsure if this is used anywhere.
    "unit_types": Array (Strings) A list of flags indicating what type of unit this is. Used by buildable_types (and probably in many other places). Accepted Values:
    • "UNITTYPE_Air"
    • "UNITTYPE_Bomber"
    • "UNITTYPE_Bot"
    • "UNITTYPE_CmdBuild"
    • "UNITTYPE_Commander"
    • "UNITTYPE_Construction"
    • "UNITTYPE_Defense"
    • "UNITTYPE_EnergyProduction"
    • "UNITTYPE_Fabber"
    • "UNITTYPE_Factory"
    • "UNITTYPE_Fighter"
    • "UNITTYPE_Land"
    • "UNITTYPE_MetalProduction"
    • "UNITTYPE_Mobile"
    • "UNITTYPE_Naval"
    • "UNITTYPE_Orbital"
    • "UNITTYPE_Scout"
    • "UNITTYPE_Structure"
    • "UNITTYPE_Tank"
    • "UNITTYPE_Tech1"
    • "UNITTYPE_Tech2"
    "wait_to_rolloff_time": Integer. How long a factory waits before telling a completed unit to move away, in seconds.

    Audio
    The audio field ("audio":) firstly contains a list of looping sounds, under "loops":. Within that are a series of entries for different sounds to be played. Each entry has the following properties:

    "cue": String. A soundback reference path (See [REFERENCE] Audio).
    "flag": String. Unsure. Accepted values:
    • "build_target_changed"
    • "vel_changed"
    "should_start_func": String. When to start the sound. Accepted values:
    • "has_build_target"
    • "no_build_target"
    • "is_moving"
    • "is_not_moving"
    "should_stop_func": String. When to stop the sound. Accepted values:
    • "has_build_target"
    • "no_build_target"
    • "is_not_moving"
    • "is_moving"

    Example, from PA\media\pa\units\commanders\base_commander\base_commander.json:
    Code:
      "audio": {
        "loops": {
          "build": {
            "cue": "/SE/Construction/Commander_contruction_beam_loop", 
            "flag": "build_target_changed", 
            "should_start_func": "has_build_target", 
            "should_stop_func": "no_build_target"
          }, 
          "move": {
            "cue": "/SE/Movement/commander/Commander_move_loop", 
            "flag": "vel_changed", 
            "should_start_func": "is_moving", 
            "should_stop_func": "is_not_moving"
          }
        }
      }, 
    Death
    TODO

    Events
    The "events" field contains a list of events, and what actions to perform when the events occur. The available events are:
    • "build_complete"
    • "destroyed"
    • "died"
    • "firing"

    Each event can have one or more of the following actions:

    "audio_cue": String. A soundback reference path (See [REFERENCE] Audio).
    "effect_spec": String. An effect reference path (Multiple allowed?)

    Example, from PA\media\pa\units\land\fabrication_vehicle_adv\fabrication_vehicle_adv.json:
    Code:
      "events": {
        "build_complete": {
          "audio_cue": "/SE/Build_Complete/structure_small"
        }, 
        "died": {
          "audio_cue": "/SE/Death/structure_small"
        }, 
        "firing": {
          "audio_cue": "/SE/Weapons/structure/artillery_long_fire", 
          "effect_spec": "/pa/effects/specs/tank_muzzle_flash.json socket_muzzle /pa/effects/specs/artillery_muzzle_ground.json"
        }
      }, 
    FX Offsets
    TODO

    Attached Files:

    Last edited: June 15, 2013
    Quitch, mysticalfists and Pendaelose like this.
  2. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    Headlights
    The headlights field presumably allows multiple headlights, as each entry is enclosed in a bracket. Each entry contains the following attributes:

    "debug": Boolean. If set to true, shows a white, untextured/shaded bounding box where the headlight is configured to be.
    "offset": Array (Float). X,Y,Z (order?) coordinates from center. Does bone override this?
    "orientation": Array (Float). The angle (X,Y,Z (order?)) at which the headlights are emitted. Does bone override this?
    "near_width": Float. TODO
    "near_height": Float. TODO
    "near_distance": Float. TODO
    "far_distance": Float. TODO
    "color": Array (Float). RGB colour, each value 0.0 -1.0.
    "intensity": Float. How bright the light is.
    "bone": Strong. The name of a bone, presumed from where the light is emitted.
    "shadow_resolution": Integer. Unknown

    Model
    The model field has the following attributes:

    "filename": String. The filename of the unit model (See [REFERENCE] Models & Textures).
    "animations": Group (key/String). A list of named animations (key) and the filename of their animation files (String).
    "animtree": String. The filename of an animtree .json file. These are stored in /PA/media/pa/anim/anim_trees/
    "walk_speed": Float. Controls the speed of the walk animation.
    "arrows": See this post.

    Navigation
    The navigation field has the following attributes:

    "type": String. The movement class of this unit. Accepted values:
    • "air"
    • "amphibious"
    • "land-small"
    • "underwater"
    • "water"
    "acceleration": Integer. Acceleration rate.
    "brake": Integer. Brake rate (reverse acceleration).
    "move_speed": Integer. Max movement speed.
    "turn_speed": Integer. Turn rate, in degrees per second?
    "dodge_radius": Integer. Unknown.
    "dodge_multiplier": Float. Unknown.
    "wobble_factor": Float. Unknown.
    "wobble_speed": Float. Unknown.

    Physics
    The physics field has the following attributes:

    "air_friction": Float. The amount of world and input forces removed per second.
    "allow_pushing": Boolean. TODO
    "gravity_scalar": Integer. Gravity modifier value.
    "ignore_collisions": Boolean. Whether the unit ignores movement collision events (eg. factories).
    "layer": Unused.
    "push_class": Integer. Unknown. Possibly higher values push lower values more when units bump.
    "radius": Float. The size of the mesh (spherical).

    Recon
    This field contains an "observer" attribute, which in turn contains an "items": attribute, which describes the intel fields (sight, radar etc) the unit has. Each field has the following attributes:

    "channel": String. The type of intel field. Accepted values:
    • "radar"
    • "sight"
    "layer": String. Which layer the intel field works on. Accepted values:
    • "surface_and_air"
    • "underwater"
    "radius": Integer. The size of the intel field.
    "shape": String. The shape of the intel field. Accepted value:
    • "capsule"

    Tools
    Tools is where the unit's weapons and building functions are defined. The model field ("tools":) has the following attributes per entry (there can be multiple entries for multiple weapons):

    "aim_bone": String. Name of the bone to aim the weapon/builder from
    "death_weapon": Boolean. Whether the weapon is triggered on death.
    "muzzle_bone": String / Array (Strings). Name of the bone(s) the weapon is fired from.
    "show_ghost": Boolean. Specifies whether the unit should leave behind a recon "ghost" when you lose line-of-sight to it (for enemy units).
    "spec_id": The filename of the tool definition .json file. (See [REFERENCE] Tool & Ammo Blueprints).

    Example, from PA\media\pa\units\sea\frigate\frigate.json:
    Code:
      "tools": [
        {
          "aim_bone": "bone_pitch02", 
          "muzzle_bone": [
            "socket_rightMuzzle02", 
            "socket_leftMuzzle02"
          ], 
          "spec_id": "/pa/units/sea/frigate/frigate_tool_weapon_aa.json"
        }, 
        {
          "aim_bone": "bone_pitch01", 
          "muzzle_bone": [
            "socket_muzzle01"
          ], 
          "spec_id": "/pa/units/sea/frigate/frigate_tool_weapon_shell.json"
        }
      ], 
    Last edited: June 15, 2013
    Quitch and Pendaelose like this.
  3. monkeyulize

    monkeyulize Active Member

    Messages:
    539
    Likes Received:
    99
    Re: Reference: Unit data files

    Lots of good information. One thing you might know since you've been poking around, do you think there is functionality in place that would allow you to change the strategic icon based on whether the unit is selected or not?

    Of course someone from uber could answer too :p
  4. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    Not that I can see at this point, it's likely not implemented yet.
    l can't even find where the mapping between icon IDs and filenames is (had to work it out manually).
  5. brandonpotter

    brandonpotter Well-Known Member

    Messages:
    966
    Likes Received:
    389
    Re: Reference: Unit data files

    Its too bad theres no way to add in your own models yet.
  6. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    We could, quite easily, if we knew the format of the meshes. I tried and it's not a standard one.
  7. lilbthebasedlord

    lilbthebasedlord Active Member

    Messages:
    249
    Likes Received:
    80
    Re: Reference: Unit data files

    On a related note, you can extract game music and sounds with an FSB extractor. Oddly, the track used in the Kickstarter is called "Russian". Oh and Raevn, do you still have the AI files for SC:TA? If you do, could you send them to me, pretty please?
  8. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    I do, but it doesn't really work that well. I'll pm them.
  9. bgolus

    bgolus Uber Alumni

    Messages:
    1,481
    Likes Received:
    2,299
    Re: Reference: Unit data files

    "arrows" in the model definition is the size of local axis aligned lines to show orientation, if the value doesn't exist, no lines. If you pause the game and look at many projectiles you can see them, on units they're usually smaller than the unit model itself so you can't even see them. Really this value should be removed or ignored by the game as its just for debugging.

    The song is called "Russian" because when when Howard started working on it the song sounded like a Russian march.

    There's a couple of things on the list not quite right or missing some info we haven't released yet, but otherwise fairly comprehensive.

    I will say the TEMP_texelinfo is a value no one understands but me. ;)
    It's a scale conversion from an uv edge distance field (the alpha channel in the diffuse texture) to in game texel size. See, you have no idea what that means either.
    It's used by the wireframe and build shaders to try to keep the line widths somewhat consistent across substantial different sized units.
    wondible likes this.
  10. DaCodeMasta

    DaCodeMasta New Member

    Messages:
    1
    Likes Received:
    0
    Re: Reference: Unit data files

    Reading this fun information that I don't know if I really understand made my night :p
  11. legitlobster

    legitlobster Member

    Messages:
    98
    Likes Received:
    0
    Re: Reference: Unit data files

    I sort of understood it.
    Uber hires me now, right?
  12. LegionDarrath

    LegionDarrath Member

    Messages:
    105
    Likes Received:
    18
    Re: Reference: Unit data files

    Hey this is pretty cool, thanks Raevn
  13. Col_Jessep

    Col_Jessep Moderator Alumni

    Messages:
    4,227
    Likes Received:
    257
    Re: Reference: Unit data files

    Raevn, please remind me to move this to the modding forum and stick it once it is available.
  14. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    Thanks :). Most of the "Possible values" lists are incomplete, I haven't gone through every unit to check what they all use, just some of the base ones and a few others. If you see any more, call them out and I'll add them to the list.

    Will do! :)
  15. feyder

    feyder Member

    Messages:
    88
    Likes Received:
    13
    Re: Reference: Unit data files

    Just a quick read, In your first Paragraph you said Sup Com Units are in JSON shouldn't it be PA? :p
  16. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
    Re: Reference: Unit data files

    Wow, you're right :lol:
  17. garat

    garat Cat Herder Uber Alumni

    Messages:
    3,344
    Likes Received:
    5,376
    Re: [REFERENCE] Unit data files

    Made it sticky. Good post, R.
  18. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
  19. bromanov

    bromanov New Member

    Messages:
    30
    Likes Received:
    0
    If you're busy, i can try and mess with the headlights a bit, show off different values of certain attributes

    however, i havent dug into modding so it may take awhile, so feel free to just ignore this and do it yourself lol

    either way, ill probably take some screenshots


    edit:

    also, taking a look at recon, can you set one channel at sight to land_and_air and another channel at radar to underwater to create ships that cant see subs, but can detect them?
  20. bromanov

    bromanov New Member

    Messages:
    30
    Likes Received:
    0
    Re: Reference: Unit data files



    would you say it sounds like a....HELL march?

Share This Page