Editing Abilities

Adding an Ability

Open: hoff-battlebuddies/shared/open/sh_abilities.lua

Find: Abilities.DB

Add your new ability at the bottom.

Example (Scratch):

scratch = {
	Name = "Scratch",
	Type = "Critter",
	Cooldown = 0,
	Accuracy = 1.0,
	Engage = "Melee",
	Knockback = -10.0,
	Icon = "ability/scratch.png",
	VFX = "GENERIC_BLOOD",
	Effects = {
		{
			On = "Resolve",
			Type = FEffectType.Damage,
			Base = 20.0,
			Increment = 13.0,
			Shake = 0.005
		}
	},
},

Ability Keys

Name Display name (overridden by localization).

Type One of: Aquatic, Beast, Critter, Dragonkin, Elemental, Flying, Humanoid, Magic, Mechanical, Undead

Cooldown Turns until the ability is usable again. 0 = no cooldown.

Accuracy Hit chance from 0.0 to 1.0.

Engage How the “attack animation” is handled:

"Melee" = standard melee attack
"Ranged" = standard ranged attack
"Swarm" = rows of pet peds charge into the enemy like ocean waves
function(CasterPed, TargetPed, Event) ... end = full scripted control (see below)

Knockback (optional) Push/pull applied during impact (if the ability uses it).

Icon Relative to: hoff-battlebuddies/ui/assets/images/ Example: "ability/scratch.png"

VFX (optional) A VFX token string (covered in the VFX section).

Effects List of effect blocks (damage, heal, apply aura, swap, multi-hit, etc).

Effects Basics (On / Base / Increment)

On timing

Cast = triggers immediately when the ability is chosen
Resolve = triggers after the Engage finishes
Kill = triggers only if the ability finishes the target

Example:

Effects = {
	{ On = "Cast",    Type = FEffectType.PositiveAura, Target = "Self", Duration = 2, Aura = "healthy" },
	{ On = "Resolve", Type = FEffectType.Damage,       Base = 10.0, Increment = 5.0 },
	{ On = "Kill",    Type = FEffectType.HealPercent,  Target = "Self", Percent = 0.2, PercentOf = "CasterMaxHP" },
}

Base + Increment (damage / heal scaling)

For FEffectType.Damage and FEffectType.Heal:

Final Amount = Base + (Increment * PetLevel)

Example: Base 10, Increment 5, Level 5 → 10 + (5 * 5) = 35

{
	On = "Resolve",
	Type = FEffectType.Damage,
	Base = 10.0,
	Increment = 5.0,
}

Custom Engage Functions

If you want a scripted “mini cutscene” instead of a normal engage type, you can replace Engage with a function.

Example (prop + anim + particles):

Engage = function(CasterPed, TargetPed, Event)
	local coords = GetEntityCoords(CasterPed)
	local groundZ = Utils.GetGroundAtCoords(coords)
	coords = vector3(coords.x, coords.y, groundZ - 0.5) + GetEntityForwardVector(CasterPed) * 1.0

	local grassProp = BattleEffects.SpawnProp(
		`hei_prop_hei_new_plant`,
		coords,
		GetEntityHeading(CasterPed) + 180.0
	)

	Wait(500)
	BattleEffects.PlayPetAnim(CasterPed, "GetPet", true)
	BattleEffects.PlayParticleEffectAttached("core", "ent_col_bush_leaves", CasterPed, vector3(0.0), 1.0, nil, 31086)

	Wait(1000)
	BattleEffects.DeleteProp(grassProp)
	Wait(250)

	-- Request immediate health update for the target pet
	if Event.targetUID then
		BattleEffects.RequestHealthUpdate(Event.targetUID, Event.extraParams.Health)
	end

	BattleEffects.ProcessDeadPets(Event)
	BattleEffects.WaitForSpeech(TargetPed)
end,

Useful BattleEffects Helpers (Engage)

These are the most useful helpers when you’re building custom engages.

Sounds

BattleEffects.PlayPedSound(ped, sound)
-- Example:
BattleEffects.PlayPedSound(TargetPed, "DEATH_GARGLE")

Particle FX

BattleEffects.PlayParticleEffectAtCoord(dict, name, coords, scale, duration, bGroundSnap)
BattleEffects.PlayParticleEffectAttached(dict, name, entity, offset, scale, duration, bone)
BattleEffects.StopParticleEffect(particleEffect)

Examples:

BattleEffects.PlayParticleEffectAtCoord("core", "blood_stab", GetEntityCoords(TargetPed))
BattleEffects.PlayParticleEffectAttached("core", "ent_col_bush_leaves", CasterPed, vector3(0.0), 1.0, nil, 31086)

Freeze / collision

BattleEffects.DisablePhysics(ped) -- freeze + collision off
BattleEffects.EnablePhysics(ped)  -- unfreeze + collision on

Props

BattleEffects.SpawnProp(modelHash, coords, heading, bCollision)
BattleEffects.DeleteProp(prop)

Example:

local chestProp = BattleEffects.SpawnProp(
	`apa_mp_h_acc_fruitbowl_02`,
	coords,
	GetEntityHeading(CasterPed) + 180.0
)

Movement / attacks / anims

BattleEffects.RunToEnemy(PetPed, EnemyPed)
BattleEffects.LaunchToEnemy(CasterPed, TargetPed, bAsync)

BattleEffects.DoRangedAttack(PetPed, bSynchronous)
BattleEffects.DoMeleeSwipe(PetPed, bSynchronous)

BattleEffects.PlayPetAnim(PetPed, animKey, bSynchronous)

Impact

BattleEffects.ApplyPetKnockback(petUID, amplitude)
BattleEffects.ShakeCam(magnitude)

Examples:

BattleEffects.ApplyPetKnockback(Event.targetUID, -10.0)
BattleEffects.ShakeCam(0.015)

Recommended Attack Footer (use this)

Any custom engage that deals damage should include this somewhere near the end:

-- Request immediate health update for the target pet
if Event.targetUID then
	BattleEffects.RequestHealthUpdate(Event.targetUID, Event.extraParams.Health)
end

-- Play death anims for anything KO’d by this hit
BattleEffects.ProcessDeadPets(Event)

-- Prevent cutting off the impact sound
BattleEffects.WaitForSpeech(TargetPed)

Adding an Aura

Auras are defined in the same file.

Open: hoff-battlebuddies/shared/open/sh_abilities.lua

Find: Abilities.Auras

Add your aura entry near the bottom.

Example (Poisoned):

poisoned = {
	Name = "Poisoned",
	Icon = "ability/poisoned.png",
	Type = "negative",
	VFX = {
		Apply = nil,
		Change = "POISONED",
		Expire = nil
	},
	Effects = {
		{
			Type = FEffectType.NegativeAura,
			Target = "Self",
			State = EBattlePetState.BATTLE_PET_STATE_Mechanic_IsPoisoned,
			Value = 1
		}
	}
},

Applying an aura from an ability

{
	On = "Resolve",
	Type = FEffectType.NegativeAura,
	Target = "Enemy",
	Duration = 5,
	Aura = "poisoned",
},

Creating VFX Types

VFX are optional, but make abilities way more satisfying.

VFX tokens live in:

Abilities.FX (same file)

VFX In Abilities

Add a token to your ability:

VFX = "GENERIC_BLOOD",

VFX In Auras

Auras can use a single token:

VFX = "HEALTHY_AURA",

Or a table (so Apply / Change / Expire can differ):

VFX = {
	Apply = "GENERIC_BLOOD_2",
	Change = "GENERIC_BLOOD_2",
	Expire = nil
},

VFX Token Formats

Most VFX tokens are either:

1) Simple particle entry

GENERIC_BLOOD = {
	Dict = "core",
	Effect = "bang_blood_car",
	Offset = vector3(0.0, -0.1, 0.0),
	BoneIndex = 31086
},

2) Custom event entry (full control)

POISONED = {
	Event = function(CasterPed, TargetPed)
		BattleEffects.PlayPedSound(TargetPed, "DEATH_GARGLE")
		BattleEffects.PlayParticleEffectAtCoord("core", "blood_stab", GetEntityCoords(TargetPed))
		Wait(1000)
	end,
},

Finding particle dictionaries / names

This free dev tool makes particle lookup way easier: https://forum.cfx.re/t/free-particle-viewer-dev-tool/5042066

Ability Effect Types

Damage / Healing

FEffectType.Damage

Flat damage using Base + (Increment * PetLevel).

{ On = "Resolve", Type = FEffectType.Damage, Base = 20.0, Increment = 13.0 }

FEffectType.Heal

Flat healing using Base + (Increment * PetLevel).

{ On = "Resolve", Type = FEffectType.Heal, Target = "Self", Base = 10.0, Increment = 5.0 }

FEffectType.HealPercent

Heals a percent of max HP (commonly used on Kill effects).

{ On = "Kill", Type = FEffectType.HealPercent, Target = "Self", Percent = 0.2, PercentOf = "CasterMaxHP" }

FEffectType.HealPercentDealt

“Lifesteal” style healing based on damage dealt. Param = { healPercent, accuracyPercent }

{ On = "Resolve", Type = FEffectType.HealPercentDealt, Target = "Self", Param = { 100, 100 } }

Percent / Conditional Damage

FEffectType.DamagePercent

Deals a percent of the target’s max HP. Param = { percent } (10 = 10%)

{ On = "Resolve", Type = FEffectType.DamagePercent, Param = { 10 } }

FEffectType.DamagePercentTaken

Deals damage based on the last hit taken. Param = { percentOfLastHitTaken, accuracyPercent }

{ On = "Resolve", Type = FEffectType.DamagePercentTaken, Param = { 100, 100 } }

FEffectType.RampingDamage

Damage that ramps up over repeated uses (with a cap). Param = { base, accuracyPercent, rampPerUse, max }

{ On = "Resolve", Type = FEffectType.RampingDamage, Param = { 15, 100, 15, 45 } }

Auras

FEffectType.PositiveAura

Applies a buff aura by key.

{ On = "Resolve", Type = FEffectType.PositiveAura, Target = "Self", Duration = 3, Aura = "healthy" }

FEffectType.NegativeAura

Applies a debuff aura by key.

{ On = "Resolve", Type = FEffectType.NegativeAura, Target = "Enemy", Duration = 5, Aura = "poisoned" }

Multi-Action Effects

FEffectType.MultiHit

Runs the nested Each effect multiple times (random hit count).

{
	On = "Resolve",
	Type = FEffectType.MultiHit,
	Hits = "1-3",
	Each = { Type = FEffectType.Damage, Base = 10.0, Increment = 6.0 }
}

FEffectType.Channel

Repeats the nested Each effect across multiple rounds.

{
	On = "Resolve",
	Type = FEffectType.Channel,
	Rounds = 2,
	Each = { Type = FEffectType.Damage, Base = 14.0, Increment = 6.0 }
}

Battle Utility

FEffectType.Catch

Capture logic for wild pets. Param = { baseChancePercent, bonusPerFailedAttemptPercent }

{ On = "Resolve", Type = FEffectType.Catch, Param = { 25, 25 } }

FEffectType.SwapHigh

Forces the enemy to swap to their highest-health pet. Param = { chancePercent }

{ On = "Resolve", Type = FEffectType.SwapHigh, Param = { 100 } }

FEffectType.ExtraAttackIfMoreFaster

Triggers an extra hit if the caster is faster. Param = { baseDamage, accuracyPercent } (plus optional Increment scaling)

{
	On = "Resolve",
	Type = FEffectType.ExtraAttackIfMoreFaster,
	Param = { 7, 100 },
	Increment = 4
}

FEffectType.Dummy

No-op effect (used for “Pass” / placeholders).

{ On = "Resolve", Type = FEffectType.Dummy }

PreviousAdding/Removing Species NextAdding Localization

Last updated 28 days ago

hashtagAdding an Ability

hashtagAbility Keys

hashtagEffects Basics (On / Base / Increment)

hashtagCustom Engage Functions

hashtagUseful BattleEffects Helpers (Engage)

hashtagRecommended Attack Footer (use this)

hashtagAdding an Aura

hashtagApplying an aura from an ability

hashtagCreating VFX Types

hashtagVFX In Abilities

hashtagVFX In Auras

hashtagVFX Token Formats

hashtagFinding particle dictionaries / names

hashtagAbility Effect Types

hashtagDamage / Healing

hashtagPercent / Conditional Damage

hashtagAuras

hashtagMulti-Action Effects

hashtagBattle Utility