games/vcmi
1
0
Fork 0
mirror of https://github.com/vcmi/vcmi.git synced 2025-11-23 22:37:55 +02:00
Code Issues Releases Activity
Files
2dca9c876659591702ee21ce887c7cdd944c2380
vcmi/docs/modders/Bonus/Bonus_Limiters.md
Ivan Savenko 4af7949571 Bonus limiters refactoring 
- Split massive `parseLimiter` method in smaller chunks
- Added alternative format for limiters with named parameters instead of
unclear `parameters` entry that often leads to bugs in mods. Old format
is still available.
- Added detailed validation for limiter format
- Converted vcmi json's to use new format
- Removed parameter-less `CREATURE_FACTION` and `SAME_FACTION` limiter.
They are unused in mods and have unclear use-case that can be replaced
by other limiters
- Expanded documentation on limiter types

All mods that were supported before should still be supported
2025-07-08 13:01:08 +03:00

4.2 KiB
Raw Blame History

Bonus Limiters

Predefined Limiters

Simple limiters that take no parameters.

Example:

"limiters" : [ "SHOOTER_ONLY" ]

SHOOTER_ONLY

Bonus is active if affected unit is a shooter (has SHOOTER bonus)

DRAGON_NATURE

Bonus is active if affected unit is a dragon (has DRAGON_NATURE bonus)

IS_UNDEAD

Bonus is active if affected unit is an undead (has UNDEAD bonus)

CREATURE_NATIVE_TERRAIN

Bonus is active if affected unit is on native terrain

CREATURES_ONLY

Bonus is active only on units

OPPOSITE_SIDE

Bonus is active only for opposite side for a battle-wide bonus. Requires BONUS_OWNER_UPDATER to be present on bonus

Customizable Limiters

HAS_ANOTHER_BONUS_LIMITER

Bonus is only active if affected entity has another bonus that meets conditions

Parameters:

  • bonusType - type of bonus to check against
  • bonusSubtype - subtype of bonus to check against (only used if bonus type is set)
  • bonusSourceType - source type of bonus to check against
  • bonusSourceID -source ID of bonus to check against (only used if bonus type is set)

All parameters are optional.

Examples:

  • Adele specialty: active if unit has any bonus from Bless spell
	"limiters" : [
		{
			"type" : "HAS_ANOTHER_BONUS_LIMITER",
			"bonusSourceType" : "SPELL_EFFECT", // look for bonus of type SPELL_EFFECT
			"bonusSourceID" : "spell.bless"     // ... from spell "Bless"
		}
	],
  • Mutare specialty: active if unit has DRAGON_NATURE bonus
	"limiters" : [
		{
			"type" : "HAS_ANOTHER_BONUS_LIMITER",
			"bonusType" : "DRAGON_NATURE"
		}
	],

CREATURE_TYPE_LIMITER

Bonus is only active on creatures of specified type

Parameters:

  • creature - ID of creature to check against
  • includeUpgrades - whether creature that is upgrade of creature should also pass this limiter. If creature has multiple upgrades, or upgrades have their own upgrades, all such creatures will be affected. Special upgrades such as upgrades via specialties (Dragon, Gelu) are not affected

Example:

"limiters": [
	{
		"type" : "CREATURE_TYPE_LIMITER",
		"creature" : "angel",
		"includeUpgrades" : true
	}
],

CREATURE_ALIGNMENT_LIMITER

Bonus is only active on creatures of factions of specified alignment

Parameters:

  • alignment - ID of alignment that creature must have, good, evil, or neutral
"limiters": [
	{
		"type" : "CREATURE_ALIGNMENT_LIMITER",
		"alignment" : "evil"
	}
],

CREATURE_LEVEL_LIMITER

If parameters is empty, any creature will pass this limiter

Parameters:

  • minLevel - minimal level that creature must have to pass limiter
  • maxlevel - maximal level that creature must have to pass limiter
"limiters": [
	{
		"type" : "CREATURE_LEVEL_LIMITER",
		"minLevel" : 1,
		"maxlevel" : 5
	}
],

FACTION_LIMITER

Also available as CREATURE_FACTION_LIMITER

Parameters:

  • faction - faction that creature or hero must belong to
"limiters": [
	{
		"type" : "FACTION_LIMITER",
		"faction" : "castle"
	}
],

CREATURE_TERRAIN_LIMITER

Parameters:

  • terrain - identifier of terrain on which this creature must be to pass this limiter. If not set, creature will pass this limiter if it is on native terrain

Example:

"limiters" : [
	{
		"type" : "CREATURE_TERRAIN_LIMITER",
		"terrain" : "sand"
	}
]

HAS_CHARGES_LIMITER

Currently works only with spells. Sets the cost of use in charges

Parameters:

  • cost - use cost (charges)
"limiters" : [
	{
		"type" : "HAS_CHARGES_LIMITER",
		"cost" : 2
	}
]

UNIT_ON_HEXES

Parameters:

  • hexes - List of affected battlefield hexes
"limiters" : [
	{
		"type" : "UNIT_ON_HEXES",
		"hexes" : [ 25, 50, 75 ]
	}
]

For reference on tiles indexes see image below:

Battlefield Hexes Layout

Aggregate Limiters

The following limiters must be specified as the first element of a list, and operate on the remaining limiters in that list:

  • allOf (default when no aggregate limiter is specified)
  • anyOf
  • noneOf

Example:

"limiters" : [
    "noneOf",
    "IS_UNDEAD",
    {
        "type" : "HAS_ANOTHER_BONUS_LIMITER",
        "parameters" : [ "SIEGE_WEAPON" ]
    }
]