Skip to content

Projectiles

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Basics

A projectile is anything that moves on its own once it is created: arrows and bullets, magic bolts and thrown knives, but also yoyos, flails, spears and grappling hooks. Weapons shoot them and enemies spawn them. A mod adds new ones with a class that extends ModProjectile, and this page covers how they are defined, how they move and hit, and how they stay in sync in multiplayer. Pets and minions are projectiles too, and have their own page: Mounts, pets and minions.

public class ExampleBullet : ModProjectile
{
    public override void SetDefaults()
    {
        Projectile.width = 8;
        Projectile.height = 8;
        Projectile.aiStyle = ProjAIStyleID.Arrow;
        Projectile.friendly = true;
        Projectile.DamageType = DamageClass.Ranged;
        Projectile.penetrate = 5;
        Projectile.timeLeft = 600;
        AIType = ProjectileID.Bullet;
    }

    public override bool OnTileCollide(Vector2 oldVelocity)
    {
        Projectile.penetrate--;
        if (Projectile.penetrate <= 0) Projectile.Kill();
        else Projectile.velocity = -oldVelocity;
        return false;
    }
}

The texture is Texture (ExampleBullet.png, frames stacked vertically: Main.projFrames[Type] in SetStaticDefaults), the name Mods.<Mod>.Projectiles.<Name>.DisplayName, and the type comes after the game's 1136 (ModContent.ProjectileType<T>(), ProjectileLoader.GetProjectile). An item shoots it with Item.shoot, and Projectile.NewProjectile spawns it. Projectile.ModProjectile is the mod's instance for that projectile.

Hook When
SetStaticDefaults, SetDefaults after the game has the type; for each new projectile (Projectile.SetDefaults)
OnSpawn(source) after Projectile.NewProjectile, with the spawn source
PreAI, AI, PostAI around the game's AI (aiStyle); AIType runs the AI of that game projectile; PreAI false skips the game's AI and AI
TileCollideStyle(ref width, ref height, ref fallThrough, ref hitboxCenterFrac) before the tile collision of each move: the box the tiles see (its size and where its center sits in the hitbox) and whether platforms let it through; false skips the tile collision for that move
OnTileCollide(oldVelocity) when the projectile hits a tile while moving; false keeps it alive where the game would kill it
CanCutTiles(), CutTiles() whether it cuts grass, vines and pots on its way (null leaves it to the game); CutTiles runs after the game's cut, to cut more
PreKill(timeLeft), OnKill(timeLeft) before Projectile.Kill; PreKill false removes it without the game's death effects
ShouldUpdatePosition false keeps it where it is this update
Colliding(projHitbox, targetHitbox) a custom hit test against NPCs and players
CanDamage, MinionContactDamage, ModifyDamageHitbox in Projectile.Damage
GetAlpha(lightColor) the color it is drawn with
PreDrawExtras(player) before the game draws the projectile's extras: a hook's chain, a flail's chain, a yoyo's string, a fishing line; false hides them and lets the mod draw its own
PreDraw(player, ref lightColor), PostDraw(player, lightColor) around the game's draw (Main.DrawProjDirect); Projectile.GetDefaultDrawData(player, lightColor) gives the draw the game would make, for afterimages; PreDraw false hides the sprite and keeps the extras

Projectile.oldPos (with ProjectileID.Sets.TrailCacheLength[Type]) reads by index as in tModLoader. Main.EntitySpriteDraw takes a Rectangle? (null is the whole texture) and an optional last argument, as in tModLoader, and Collision.CheckAABBvLineCollision(..., lineWidth, ref collisionPoint) tests a thick line against a box. Projectile.CloneDefaults(type) copies another projectile's defaults and keeps the type, the ModProjectile and the globals.

Projectiles in multiplayer: SendExtraAI

The game syncs a projectile's position, velocity and ai with its message 27; fields of your own travel with SendExtraAI(BinaryWriter writer) and ReceiveExtraAI(BinaryReader reader). Set Projectile.netUpdate = true in AI when they change (the game clears it right before the AI, so setting it elsewhere does nothing), and read them back in the same order.

public override void SendExtraAI(BinaryWriter writer) => writer.Write((byte)fishingLineColorIndex);

public override void ReceiveExtraAI(BinaryReader reader) => fishingLineColorIndex = reader.ReadByte();

A GlobalProjectile has SendExtraAI(projectile, bitWriter, binaryWriter) and ReceiveExtraAI(projectile, bitReader, binaryReader): BitWriter.WriteBit packs flags. The data is laid out as in tModLoader (the globals' bits, then the ModProjectile's bytes, then the globals' bytes), and reading less or more than was written is logged as an error. It travels with the game's message, from the projectile's owner; the server passes a client's on to the others. ProjectileLoader.WriteExtraAI/ReceiveExtraAI are public, as in tModLoader.

On the phone the extras and the sprite are drawn by the same game method, the extras first. When only one of them is hidden, the draws are told apart by the texture: until the first draw with the projectile's own texture they are extras, from it on they are the sprite.

Grappling hooks

A hook is a projectile with aiStyle = ProjAIStyleID.Hook (7), shot by an item whose shoot is that type; Projectile.CloneDefaults(ProjectileID.GemHookAmethyst) is the usual start. The ExampleMod's ExampleHook (Content/Items/Tools) uses every hook below and draws its own chain in PreDrawExtras.

Hook When
CanUseGrapple(player) before the hook is shot; false stops it, true shoots it even past the game's limit of hooks in flight, null leaves it to the game
UseGrapple(player, ref type) right before the projectile is created; change type to shoot another hook (the Dual Hook does this)
GrappleRange() how far the hook flies before it comes back (300 by default); a hook with AIType keeps that game hook's range
NumGrappleHooks(player, ref numHooks) how many hooks may be latched at once; the oldest goes when a new one latches past it
GrappleRetreatSpeed(player, ref speed) the speed back to the player when it misses (11 by default)
GrapplePullSpeed(player, ref speed) how fast the player is pulled (11 by default); the first latched hook decides
GrappleTargetPoint(player, ref grappleX, ref grappleY) the point the player is pulled to; starts at the sum of the latched hooks' centers so far
GrappleCanLatchOnTo(player, x, y) whether the hook may latch onto the tile at (x, y); null uses the game's rule (solid tiles)

GlobalProjectile has the same hooks with the Projectile first, except CanUseGrapple(type, player) and UseGrapple(player, ref type), which take the hook's type (AppliesToEntity is asked on a sample projectile of that type), and GrappleRange, which is only on ModProjectile. As in tModLoader, a global's false in GrappleCanLatchOnTo wins over everything else.

Hits

Hook When
CanHitNPC(target) before the game checks whether the projectile may hit this NPC; false never hits it, true hits it even where the game would skip it (critters), null leaves it to the game
ModifyHitNPC(target, ref modifiers), OnHitNPC(target, hit, damageDone) around the strike, as for items: modifiers start with the projectile's DamageType and the NPC's defense
CanHitPlayer(target), CanHitPvp(target) before a hostile projectile (or a PvP one) hurts a player; false stops it
ModifyHitPlayer(target, ref modifiers), OnHitPlayer(target, info) around Player.Hurt when the projectile is the cause

The order is tModLoader's: for a hit on an NPC, the owner's ModPlayer.CanHitNPC and CanHitNPCWithProj, then the projectile's CanHitNPC (the first answer that is not null wins, a false before it stops); then ModifyHitNPC on the projectile, its GlobalProjectiles, the owner's ModPlayer.ModifyHitNPC and ModifyHitNPCWithProj, and OnHitNPC in the same order. A true from CanHitNPC does not make a friendly NPC hittable.

The strike is found without running C# for every projectile: a native marker on Projectile.Damage_PVE says which projectile is dealing damage, and only the strike itself calls the mod. CanHitNPC is the exception: the game asks it for every NPC near every friendly projectile, so override it only when needed.

Melee weapons that are projectiles

Most melee weapons past the plain sword are a projectile the item shoots, and the ExampleMod has one of each (Content/Items/Weapons, Content/Items/Tools and their projectiles in Content/Projectiles):

Example How it works
ExampleShortsword ItemUseStyleID.Rapier, noMelee, noUseGraphic; the projectile (aiStyle = -1) sticks out of the hand for 16 updates, hits with Colliding and cuts grass with CutTiles
ExampleSpear ItemID.Sets.Spears, CloneDefaults(ProjectileID.Spear); the thrust is its own PreAI
ExampleFlail ProjAIStyleID.Flail with AIType = ProjectileID.Sunfury; channel spins it, letting go throws it
ExampleYoyo ItemID.Sets.Yoyo, ProjAIStyleID.Yoyo and the ProjectileID.Sets.Yoyos* sets
ExampleWhip Item.DefaultToWhip, ProjectileID.Sets.IsAWhip, a WhipTagEffect in ItemID.Sets.UniqueTagEffects; draws itself from Projectile.FillWhipControlPoints
ExampleSwingingEnergySword a projectile per swing (shootsEveryUse) that hits in a cone
ExampleDrill ItemID.Sets.IsDrill, channel; the projectile follows the cursor and mines with the item's pick
ExamplePickaxe, ExampleHamaxe plain tools with MeleeEffects dust; the pickaxe sometimes shows ExamplePickaxeEmote

Projectile.WhipSettings (Segments, RangeMultiplier) starts with what the game uses for that projectile (20 and 1 for a mod whip) and, once changed, is what the game's Projectile.GetWhipSettings returns: the hit test and FillWhipControlPoints follow it. SetDefaults puts it back. Projectile.FillWhipControlPoints(proj, List<Vector2>, player) fills a C# list.

Item.attackSpeedOnlyAffectsWeaponAnimation is kept per item type: the attack speed of a mod damage class then speeds up the swing but not the use time, as tModLoader does for tools. The game's own melee speed never shortens a melee tool's use time on the phone. ItemID.Sets.Spears only marks spears, as in tModLoader (which reads it for the game's spears only).

Not on the phone: FlailStats and FlailSpinCollisionRange (the flail's numbers are local variables of the game's flail AI, picked by projectile type, so a flail with AIType gets that flail's numbers) and DisplayDollSettings (weapons held by mannequins).


← Recipes  ·  NPCs →

Clone this wiki locally