[Documentation] Soldier Skill Menu

[memmaker]

Soldier Skills Docs

So, there is a new feature in OXCE: Soldier Skill Menus.

It allows for skill menu to be defined via rulesets. An icon will be displayed, for soldier types which have skills assigned, in the battlescape, where the the special weapon icon is, in the top right corner. This of course means, that only one of these icons can be shown at the same time. So no special weapon icon and skill menu item at the same time.

So what is a skill as defined in this feature?

A skill is a battlescape action that can be selected through the skill menu and is usually tied to an item. So a skill menu entry can act as any item action.

But a skill can also be used as a trigger for a script, using the new "skillUseUnit" script hook.

As opposed to item usage, skills can have a zero TU activation cost, but need at least a non-zero mana cost then. So no zero cost skills, it's at least some TU or some Mana for activation.

Since skills are a distinct object in terms of the rulesets, they can also have tags and scripts assigned to them.

Here is a small ruleset example which I will discuss:

Code: [Select]

mana:
  enabled: true
  battleUI: true
  trainingPrimary: false
  trainingSecondary: false
  replenishAfterMission: true

skills:
  - type: STR_RUN_AND_GUN # script activated
    tags:
      SKILL_ID: 1
    costUse:
      time: 0
      mana: 12
    flatUse:
      mana: true
  - type: STR_SLASH
    tags:
      SKILL_ID: 2
    costUse:
      time: 5
      mana: 5
    flatUse:
      mana: true
    targetMode: 10
    compatibleWeapons: [STR_STUN_ROD, STR_ALLOY_SWORD]
  - type: STR_HEAL
    tags:
      SKILL_ID: 3
    costUse:
      time: 5
      mana: 6
    flatUse:
      mana: true
      time: true
    compatibleWeapons: [STR_MEDI_KIT]
    checkHandsOnly: true
  - type: STR_RAPID_FIRE
    tags:
      SKILL_ID: 4
    costUse:
      time: 50
      mana: 5
    flatUse:
      mana: true
      time: false
    targetMode: 7 # auto
    battleType: 1 # firearms
    requiredBonuses: [STR_MY_SOLDIER_BONUS1, STR_MY_SOLDIER_BONUS1]
  - type: STR_REAPER # script activated
    requiredBonus: [STR_RANGER_ELITE_BONUS]
    isPsiRequired: true
    tags:
      SKILL_ID: 5
    costUse:
      time: 0
      mana: 12
    flatUse:
      mana: true

soldiers:
  - type: STR_SOLDIER
    minStats:
      mana: 100
    maxStats:
      mana: 100
    statCaps:
      mana: 100
    skillIconSprite: 1
    skills:
      - STR_RUN_AND_GUN # script activated
      - STR_SLASH
      - STR_HEAL
      - STR_RAPID_FIRE
      - STR_REAPER # script activated

items:
  - type: STR_RIFLE
    tuAuto: 0
    confAuto:
      shots: 4

extended:
  tags:
    RuleSkill:
      SKILL_ID: int
  scripts:
    skillUseUnit:
      - offset: 22
        code: |
          var int skill_id;

          skill.getTag skill_id Tag.SKILL_ID;
         
          battle_game.flashMessage "SkillUse triggered {0} {1}" skill_id have_tu;

          if eq have_tu 0;
            debug_log "No Resources. Aborted.";
            set continue_action 0;
            return;
          end;

          # do stuff here

          return;

So, I start out with enabling mana, since I will use that resource for some of the scripted skill activations.

Then there is a new block "skills:", which will globally define all skills which are available.

We have: name (type), tags, cost of use and the flags for flat vs. percentage. All of these attributes should be well known from item definitions.

One of the most important attributes is called "targetMode". This tells the game which battleaction will be carried out and what kind of targeting behaviour should occur. So let's talk about them for a bit.

There are:

Code: [Select]

# 0   = No target needed (Just activation, script takes over) - BA_NONE
# 10  = Melee Range Targeted (1 Tile) - BA_HIT
# mul = Firearm (Default firarm targeting) - SNAP = 8, AUTO = 7, AIMED = 9
# mul = Psi Targeting (Default PSI Targeting, with or without LOS) - BA_USE = 11, BA_MINDCONTROL = 13, BA_PANIC = 14
# 6   = Thrown Targeting (Default Thrown targeting, uses throwing arc) - BA_THROW
# 12  = Waypoint Targeting (Default blaster launcher targeting) - BA_LAUNCH

0 is the one you want to use for completely scripted skills.
All the other modes will tell the game to switch to a specific targeting behaviour you will know from the weapons already in the game.

Every targetMode, except mode 0, expects an item to present in order to work. After all, a melee action needs at least a stick and if you want to fire a gun.. you better have one.

There are currently two ways to tell the game which item to use: "compatibleWeapons" and "battleType".

"compatibleWeapons" takes a list of item names and will look for them in the hands of the respective soldier and will use the first weapon it finds.
There is a switch called "checkHandsOnly", defaulting to true, which you can switch off, in order to enable the skill to search through the whole inventory of the soldier for a compatible weapon. When "checkHandsOnly" is disabled, also special weapons of the soldier will be checked, this can be used to great effect.

You can also define a compatible "battleType":

Code: [Select]

0 - None (Geoscape-only item)
1 - Firearm
2 - Ammo
3 - Melee
4 - Grenade
5 - Proximity Grenade
6 - Medi-Kit
7 - Motion Scanner
8 - Mind Probe
9 - Psi-Amp
10 - Electro-flare
11 - Corpse

And the skill would look through the soldiers inventory (this time ignoring checkHandsOnly) for an item which matches the battletype and will use the first one it finds. This is currently the only check carried out, so it won't check if the specified targetMode is available, for example.

Now we have some skill defined, what can we do with them?

You can see, that the "soldiers:" section in the ruleset allows for two new attributes: "skillIconSprite" and "skills".

"skillIconSprite" works just like "specialIconSprite" with the same syntax and semantic just applying to the soldier type's skill menu.

"skills" is a list of names of skills this soldier type should have available. There is currently a limit of 5 skills so don't expect more entries than this to show up.

I have also included a rifle item to show what skills can do: You may notice that I disabled auto-shot on the rifle by assigning a TU cost of zero. That means it won't be selectable by the player when he clicks on his gun. But a skill can still use that action: The "STR_RAPID_FIRE" skill defined above has its "targetMode" set to auto and will use any item with a "battleType" of firearm. So if a player has the rifle equipped and activates that skill, the auto shot of the rifle will be triggered. The action costs will be as defined by the skill.

This is already pretty powerful, but with some additional scripting, even more can be done.

There is a new script called "skillUseUnit" which receives the unit currently acting ("actor"), the selected "battle_action" the item being used (if any) and the skill itself which triggered the script.

The script implementation itself can now decide wether to spend the TU for the action and carry on or not to spend any TU and cancel the action.

This enables scripts to act as a battle action in their own rights and is a useful addition to a modder's toolkit.

Additionally, the "hitUnit" and "damageUnit" script now also receive a reference to the script which initiated the action, if applicable. Thus enabling skill based "on hit" and "on damage" effects.

Hope I covered everything, questions please 

[memmaker]

One more thing: Grenades.

The skill menu currently only supports instant grenades, no priming, no unpriming. Every grenade associated with a throw action will have it's fuse enabled and set to zero upon throwing.

Another thing: Convenience.

The skill menu uses the same hotkey as the special weapon menu to pop up. So it can be toggled via keyboard shortcut. Also every skill item is assigned a hotkey (keyBattleActionItem1-5).

And still one more thing: Bonus requirements.

You can see that I used the attribute "requiredBonuses" to specify a requirement. If the soldier in question does not have these soldier bonuses applied, he will not see the corresponding entry in the skill menu.

[ohartenstein23]

This looks like a super-useful feature, I can already think of a handful of ways to update the 40k mod with skills over just special weapons.

When the skill list in battlescape is populated with items, does it only show skills for which you meet the item requirements? For example, if I gave a soldier type more than 5 skills, but tied each to a specific set of mutually-exclusive special weapons on armor, would the skill menu have different actions based on the armor? Or another example: if my soldier doesn't have the bonuses required for a specific skill, say STR_REAPER in your example ruleset, will that skill show up in the menu?

[memmaker]

When the skill list in battlescape is populated with items, does it only show skills for which you meet the item requirements?

No. The entries would still show up, but when using them and you do not have the required item it will flash a message: "This skill requires an item."

For example, if I gave a soldier type more than 5 skills, but tied each to a specific set of mutually-exclusive special weapons on armor, would the skill menu have different actions based on the armor?

No, it is tied to the soldier not the armor. However, you could use scripts to at least have different effects triggered based on the armor the soldier is wearing.

Or another example: if my soldier doesn't have the bonuses required for a specific skill, say STR_REAPER in your example ruleset, will that skill show up in the menu?

No. This is the only parameter that really controls the display. You can for example define 5 skills and have each depend on a different bonus. And only those with the acquired bonuses would show.

[Nord]

Correct me if something wrong:
If i want my soldier to throw fireballs from empty hands, i can use specialweapon and forget about skills.
If i want my soldier to throw fireballs from empty hands and replenish HP's or TU's with mana, i can use skills and special weapons.
If i want my soldier to throw fireballs or lightning bolts from empty hands, i can forget about it.
Thanks.

[memmaker]

If i want my soldier to throw fireballs from empty hands, i can use specialweapon and forget about skills.

Technically the special weapon is still an item. But you can make an item which throws fireballs and assign them as special weapon, yes.

If i want my soldier to throw fireballs from empty hands and replenish HP's or TU's with mana, i can use skills and special weapons.

You can already replenish TU and HP with mana without using skills. Not sure what the intended use case is here?

If i want my soldier to throw fireballs or lightning bolts from empty hands, i can forget about it.

Sorry, could you rephrase that? I seem to not understand.

[Nord]

Second case - using item and scripted skill. It is possible as i understand.
Third case - as i think, it is impossible to create two skills, using different special weapons. So that soldier can use two weapons without having them in his inventory. Or is this somehow possible?

[memmaker]

@Nord:

No, this does not add another special weapon.

[Nord]

Looks like specialWeapon defined in soldier rule, blocks skill button. How to use them simultaneously?

[memmaker]

They are not designed to be used to together. The icons that is.
It is only one icon that gets placed there.
Either a special Weapon or the skills. Since the skill menu can do most of the things a specialweapon could, the latter would be the more flexible solution.

You can however have a skill menu and a special weapon without the icon. Using the skill menu to pass through specific actions to the special weapon.

[Nord]

You can however have a skill menu and a special weapon without the icon. Using the skill menu to pass through specific actions to the special weapon.

Oh, did'nt know that special weapon without icon is possible. It works fine. Thanks.

One more thing: how to use panic attack through skills?

[Nord]

# 0   = No target needed (Just activation, script takes over) - BA_NONE
# 10  = Melee Range Targeted (1 Tile) - BA_HIT
# mul = Firearm (Default firarm targeting) - SNAP = 8, AUTO = 7, AIMED = 9
# mul = Psi Targeting (Default PSI Targeting, with or without LOS) - BA_USE = 11, BA_MINDCONTROL = 13, BA_PANIC = 14
# 6   = Thrown Targeting (Default Thrown targeting, uses throwing arc) - BA_THROW
# 12  = Waypoint Targeting (Default blaster launcher targeting) - BA_LAUNCH

What about healing? To use most of doping abilities we need not hitUnit, but healUnit. How to access that?
I have tried to give

Code: [Select]

    targetMode: 10 # closeBut then no healUnit goes.

[memmaker]

Hi Nord,

The list there has all the targeting modes (which are derived from the internal battle actions). Medi-Kits have no special handling regarding the targeting. They use BA_USE as a battle action as do most special inventory items, iirc. So a skill with a medi-kit and targetMode: 11 should be what you are looking for.

[Nord]

Thanks. It works...
But "healUnit" have no "skill" parameter of RuleSkill type.

[memmaker]

It has not been added to that call, yet. True.