ModPlayer
A ModPlayer instance represents an extension of a Player instance. You can store fields in the ModPlayer classes, much like how the Player class abuses field usage, to keep track of mod-specific information on the player that a ModPlayer instance represents. It also contains hooks to insert your code into the Player class.
Methods
- Autoload(System.String@)()
- Allows you to automatically add a ModPlayer instead of using Mod.AddPlayer. Return true to allow autoloading; by default returns the mod's autoload property. Name is initialized to the overriding class name. Use this to either force or stop an autoload, or change the name that identifies this type of ModPlayer.
- Initialize()
- Called whenever the player is loaded (on the player selection screen). This can be used to initialize data structures, etc.
- ResetEffects()
- This is where you reset any fields you add to your ModPlayer subclass to their default states. This is necessary in order to reset your fields if they are conditionally set by a tick update but the condition is no longer satisfied.
- UpdateDead()
- Similar to UpdateDead, except this is only called when the player is dead. If this is called, then ResetEffects will not be called.
- PreSaveCustomData()
- Currently never gets called, so this is useless.
- Save()
- Allows you to save custom data for this player. Returns null by default.
- Load(Terraria.ModLoader.IO.TagCompound)()
- Allows you to load custom data you have saved for this player.
- LoadLegacy(System.IO.BinaryReader)()
- Allows you to load pre-v0.9 custom data you have saved for this player.
- SetupStartInventory(System.Collections.Generic.IList{Terraria.Item},System.Boolean)()
- Allows you to modify the inventory newly created players or killed mediumcore players will start with. To add items to the player's inventory, create a new Item, call its SetDefaults method for whatever ID you want, call its Prefix method with a parameter of -1 if you want to give it a random prefix, then add it to the items list parameter.
- PreSavePlayer()
- PreSavePlayer and PostSavePlayer wrap the vanilla player saving code (both are before the ModPlayer.Save). Useful for advanced situations where a save might be corrupted or rendered unusable by the values that normally would save.
- PostSavePlayer()
- PreSavePlayer and PostSavePlayer wrap the vanilla player saving code (both are before the ModPlayer.Save). Useful for advanced situations where a save might be corrupted or rendered unusable by the values that normally would save.
- UpdateBiomes()
- Allows you to set biome variables in your ModPlayer class based on tile counts.
- CustomBiomesMatch(Terraria.Player)()
- Whether or not this player and the other player parameter have the same custom biome variables. This hook is used to help with client/server syncing. Returns true by default.
- CopyCustomBiomesTo(Terraria.Player)()
- In this hook, you should copy the custom biome variables from this player to the other player parameter. This hook is used to help with client/server syncing.
- SendCustomBiomes(System.IO.BinaryWriter)()
- Allows you to send custom biome information between client and server.
- ReceiveCustomBiomes(System.IO.BinaryReader)()
- Allows you to do things with the custom biome information you send between client and server.
- UpdateBiomeVisuals()
- Allows you to create special visual effects in the area around the player. For example, the blood moon's red filter on the screen or the slime rain's falling slime in the background. You must create classes that override Terraria.Graphics.Shaders.ScreenShaderData or Terraria.Graphics.Effects.CustomSky, add them in your mod's Load hook, then call Player.ManageSpecialBiomeVisuals. See the ExampleMod if you do not have access to the source code.
- clientClone(Terraria.ModLoader.ModPlayer)()
- Allows you to copy information about this player to the clientClone parameter. You should copy information that you intend to sync between server and client. This hook is called in the Player.clientClone method. See SendClientChanges for more info.
- SyncPlayer(System.Int32,System.Int32,System.Boolean)()
- Allows you to sync information about this player between server and client. The toWho and fromWho parameters correspond to the remoteClient/toClient and ignoreClient arguments, respectively, of NetMessage.SendData/ModPacket.Send. The newPlayer parameter is whether or not the player is joining the server (it is true on the joining client).
- SendClientChanges(Terraria.ModLoader.ModPlayer)()
- Allows you to sync any information that has changed between the server and client. Here, you should check the information you have copied in the clientClone parameter; if they differ between this player and the clientPlayer parameter, then you should send that information using NetMessage.SendData or ModPacket.Send.
- GetMapBackgroundImage()
- Allows you to change the background that displays when viewing the map. Return null if you do not want to change the background. Returns null by default.
- UpdateBadLifeRegen()
- Allows you to give the player a negative life regeneration based on its state (for example, the "On Fire!" debuff makes the player take damage-over-time). This is typically done by setting player.lifeRegen to 0 if it is positive, setting player.lifeRegenTime to 0, and subtracting a number from player.lifeRegen. The player will take damage at a rate of half the number you subtract per second.
- UpdateLifeRegen()
- Allows you to increase the player's life regeneration based on its state. This can be done by incrementing player.lifeRegen by a certain number. The player will recover life at a rate of half the number you add per second. You can also increment player.lifeRegenTime to increase the speed at which the player reaches its maximum natural life regeneration.
- NaturalLifeRegen(System.Single@)()
- Allows you to modify the power of the player's natural life regeneration. This can be done by multiplying the regen parameter by any number. For example, campfires multiply it by 1.1, while walking multiplies it by 0.5.
- UpdateAutopause()
- Allows you to modify the player's stats while the game is paused due to the autopause setting being on. This is called in single player only, some time before the player's tick update would happen when the game isn't paused.
- PreUpdate()
- This is called at the beginning of every tick update for this player, after checking whether the player exists.
- ProcessTriggers(Terraria.GameInput.TriggersSet)()
- Use this to check on hotkeys you have registered. While SetControls is set even while in text entry mode, this hook is only called during gameplay.
- SetControls()
- Use this to modify the control inputs that the player receives. For example, the Confused debuff swaps the values of player.controlLeft and player.controlRight. This is called sometime after PreUpdate is called.
- PreUpdateBuffs()
- This is called sometime after SetControls is called, and right before all the buffs update on this player. This hook can be used to add buffs to the player based on the player's state (for example, the Campfire buff is added if the player is near a Campfire).
- PostUpdateBuffs()
- This is called right after all of this player's buffs update on the player. This can be used to modify the effects that the buff updates had on this player, and can also be used for general update tasks.
- UpdateEquips(System.Boolean@,System.Boolean@,System.Boolean@)()
- Called after Update Accessories.
- PostUpdateEquips()
- This is called right after all of this player's equipment and armor sets update on the player, which is sometime after PostUpdateBuffs is called. This can be used to modify the effects that the equipment had on this player, and can also be used for general update tasks.
- PostUpdateMiscEffects()
- This is called after miscellaneous update code is called in Player.Update, which is sometime after PostUpdateEquips is called. This can be used for general update tasks.
- PostUpdateRunSpeeds()
- This is called after the player's horizontal speeds are modified, which is sometime after PostUpdateMiscEffects is called, and right before the player's horizontal position is updated. Use this to modify maxRunSpeed, accRunSpeed, runAcceleration, and similar variables before the player moves forwards/backwards.
- PreUpdateMovement()
- This is called right before modifying the player's position based on velocity. Use this to make direct changes to the velocity.
- PostUpdate()
- This is called at the very end of the Player.Update method. Final general update tasks can be placed here.
- UpdateVanityAccessories()
- This is called after VanillaUpdateVanityAccessory() in player.UpdateEquips()
- FrameEffects()
- Allows you to modify the armor and accessories that visually appear on the player. In addition, you can create special effects around this character, such as creating dust.
- PreHurt(System.Boolean,System.Boolean,System.Int32@,System.Int32@,System.Boolean@,System.Boolean@,System.Boolean@,System.Boolean@,Terraria.DataStructures.PlayerDeathReason@)()
- This hook is called before every time the player takes damage. The pvp parameter is whether the damage was from another player. The quiet parameter determines whether the damage will be communicated to the server. The damage, hitDirection, and crit parameters can be modified. Set the customDamage parameter to true if you want to use your own damage formula (this parameter will disable automatically subtracting the player's defense from the damage). Set the playSound parameter to false to disable the player's hurt sound, and the genGore parameter to false to disable the dust particles that spawn. (These are useful for creating your own sound or gore.) The deathText parameter can be modified to change the player's death message if the player dies. Return false to stop the player from taking damage. Returns true by default.
- Hurt(System.Boolean,System.Boolean,System.Double,System.Int32,System.Boolean)()
- Allows you to make anything happen right before damage is subtracted from the player's health.
- PostHurt(System.Boolean,System.Boolean,System.Double,System.Int32,System.Boolean)()
- Allows you to make anything happen when the player takes damage.
- PreKill(System.Double,System.Int32,System.Boolean,System.Boolean@,System.Boolean@,Terraria.DataStructures.PlayerDeathReason@)()
- This hook is called whenever the player is about to be killed after reaching 0 health. Set the playSound parameter to false to stop the death sound from playing. Set the genGore parameter to false to stop the gore and dust from being created. (These are useful for creating your own sound or gore.) Return false to stop the player from being killed. Only return false if you know what you are doing! Returns true by default.
- Kill(System.Double,System.Int32,System.Boolean,Terraria.DataStructures.PlayerDeathReason)()
- Allows you to make anything happen when the player dies.
- PreItemCheck()
- Allows you to do anything before the update code for the player's held item is run. Return false to stop the held item update code from being run (for example, if the player is frozen). Returns true by default.
- PostItemCheck()
- Allows you to do anything after the update code for the player's held item is run. Hooks for the middle of the held item update code have more specific names in ModItem and ModPlayer.
- UseTimeMultiplier(Terraria.Item)()
- Allows you to multiply an item's regular use time. Returns 1f by default.
- MeleeSpeedMultiplier(Terraria.Item)()
- Allows you to multiply an item's regular melee speed. Returns 1f by default.
- GetHealLife(Terraria.Item,System.Boolean,System.Int32@)()
- Allows you to temporarily modify the amount of life a life healing item will heal for, based on player buffs, accessories, etc. This is only called for items with a healLife value.
- GetHealMana(Terraria.Item,System.Boolean,System.Int32@)()
- Allows you to temporarily modify the amount of mana a mana healing item will heal for, based on player buffs, accessories, etc. This is only called for items with a healMana value.
- GetWeaponDamage(Terraria.Item,System.Int32@)()
- Allows you to temporarily modify a weapon's damage based on player buffs, etc. This is useful for creating new classes of damage, or for making subclasses of damage (for example, Shroomite armor set boosts).
- GetWeaponKnockback(Terraria.Item,System.Single@)()
- Allows you to temporarily modify a weapon's knockback based on player buffs, etc. This allows you to customize knockback beyond the Player class's limited fields.
- GetWeaponCrit(Terraria.Item,System.Int32@)()
- Allows you to temporarily modify a weapon's crit chance based on player buffs, etc.
- ConsumeAmmo(Terraria.Item,Terraria.Item)()
- Whether or not ammo will be consumed upon usage. Return false to stop the ammo from being depleted. Returns true by default. If false is returned, the OnConsumeAmmo hook is never called.
- OnConsumeAmmo(Terraria.Item,Terraria.Item)()
- Allows you to make things happen when ammo is consumed. Called before the ammo stack is reduced.
- Shoot(Terraria.Item,Microsoft.Xna.Framework.Vector2@,System.Single@,System.Single@,System.Int32@,System.Int32@,System.Single@)()
- This is called before this player's weapon creates a projectile. You can use it to create special effects, such as changing the speed, changing the initial position, and/or firing multiple projectiles. Return false to stop the game from shooting the default projectile (do this if you manually spawn your own projectile). Returns true by default.
- MeleeEffects(Terraria.Item,Microsoft.Xna.Framework.Rectangle)()
- Allows you to give this player's melee weapon special effects, such as creating light or dust.
- OnHitAnything(System.Single,System.Single,Terraria.Entity)()
- This hook is called when a player damages anything, whether it be an NPC or another player, using anything, whether it be a melee weapon or a projectile. The x and y parameters are the coordinates of the victim parameter's center.
- CanHitNPC(Terraria.Item,Terraria.NPC)()
- Allows you to determine whether a player can hit the given NPC by swinging a melee weapon. Return true to allow hitting the target, return false to block this player from hitting the target, and return null to use the vanilla code for whether the target can be hit. Returns null by default.
- ModifyHitNPC(Terraria.Item,Terraria.NPC,System.Int32@,System.Single@,System.Boolean@)()
- Allows you to modify the damage, knockback, etc., that this player does to an NPC by swinging a melee weapon.
- OnHitNPC(Terraria.Item,Terraria.NPC,System.Int32,System.Single,System.Boolean)()
- Allows you to create special effects when this player hits an NPC by swinging a melee weapon (for example how the Pumpkin Sword creates pumpkin heads).
- CanHitNPCWithProj(Terraria.Projectile,Terraria.NPC)()
- Allows you to determine whether a projectile created by this player can hit the given NPC. Return true to allow hitting the target, return false to block this projectile from hitting the target, and return null to use the vanilla code for whether the target can be hit. Returns null by default.
- ModifyHitNPCWithProj(Terraria.Projectile,Terraria.NPC,System.Int32@,System.Single@,System.Boolean@,System.Int32@)()
- Allows you to modify the damage, knockback, etc., that a projectile created by this player does to an NPC.
- OnHitNPCWithProj(Terraria.Projectile,Terraria.NPC,System.Int32,System.Single,System.Boolean)()
- Allows you to create special effects when a projectile created by this player hits an NPC (for example, inflicting debuffs).
- CanHitPvp(Terraria.Item,Terraria.Player)()
- Allows you to determine whether a melee weapon swung by this player can hit the given opponent player. Return false to block this weapon from hitting the target. Returns true by default.
- ModifyHitPvp(Terraria.Item,Terraria.Player,System.Int32@,System.Boolean@)()
- Allows you to modify the damage, etc., that a melee weapon swung by this player does to an opponent player.
- OnHitPvp(Terraria.Item,Terraria.Player,System.Int32,System.Boolean)()
- Allows you to create special effects when this player's melee weapon hits an opponent player.
- CanHitPvpWithProj(Terraria.Projectile,Terraria.Player)()
- Allows you to determine whether a projectile created by this player can hit the given opponent player. Return false to block the projectile from hitting the target. Returns true by default.
- ModifyHitPvpWithProj(Terraria.Projectile,Terraria.Player,System.Int32@,System.Boolean@)()
- Allows you to modify the damage, etc., that a projectile created by this player does to an opponent player.
- OnHitPvpWithProj(Terraria.Projectile,Terraria.Player,System.Int32,System.Boolean)()
- Allows you to create special effects when a projectile created by this player hits an opponent player.
- CanBeHitByNPC(Terraria.NPC,System.Int32@)()
- Allows you to determine whether the given NPC can hit this player. Return false to block this player from being hit by the NPC. Returns true by default. CooldownSlot determines which of the player's cooldown counters to use (-1, 0, or 1), and defaults to -1.
- ModifyHitByNPC(Terraria.NPC,System.Int32@,System.Boolean@)()
- Allows you to modify the damage, etc., that an NPC does to this player.
- OnHitByNPC(Terraria.NPC,System.Int32,System.Boolean)()
- Allows you to create special effects when an NPC hits this player (for example, inflicting debuffs).
- CanBeHitByProjectile(Terraria.Projectile)()
- Allows you to determine whether the given hostile projectile can hit this player. Return false to block this player from being hit. Returns true by default.
- ModifyHitByProjectile(Terraria.Projectile,System.Int32@,System.Boolean@)()
- Allows you to modify the damage, etc., that a hostile projectile does to this player.
- OnHitByProjectile(Terraria.Projectile,System.Int32,System.Boolean)()
- Allows you to create special effects when a hostile projectile hits this player.
- CatchFish(Terraria.Item,Terraria.Item,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32@,System.Boolean@)()
- Allows you to change the item the player gains from catching a fish. The fishingRod and bait parameters refer to the said items in the player's inventory. The liquidType parameter is 0 if the player is fishing in water, 1 for lava, and 2 for honey. The poolSize parameter is the tile size of the pool the player is fishing in. The worldLayer parameter is 0 if the player is in the sky, 1 if the player is on the surface, 2 if the player is underground, 3 if the player is in the caverns, and 4 if the player is in the underworld. The questFish parameter is the item ID for the day's Angler quest. Modify the caughtType parameter to change the item the player catches. The junk parameter is whether the player catches junk; you can set this to true if you make the player catch a junk item, and is mostly used to pass information (has no effect on the game).
- GetFishingLevel(Terraria.Item,Terraria.Item,System.Int32@)()
- Allows you to modify the player's fishing power. As an example of the type of stuff that should go here, the phase of the moon can influence fishing power.
- AnglerQuestReward(System.Single,System.Collections.Generic.List{Terraria.Item})()
- Allows you to add to, change, or remove from the items the player earns when finishing an Angler quest. The rareMultiplier is a number between 0.15 and 1 inclusively; the lower it is the higher chance there should be for the player to earn rare items.
- GetDyeTraderReward(System.Collections.Generic.List{System.Int32})()
- Allows you to modify what items are possible for the player to earn when giving a Strange Plant to the Dye Trader.
- DrawEffects(Terraria.ModLoader.PlayerDrawInfo,System.Single@,System.Single@,System.Single@,System.Single@,System.Boolean@)()
- Allows you to create special effects when this player is drawn, such as creating dust, modifying the color the player is drawn in, etc. The fullBright parameter makes it so that the drawn player ignores the modified color and lighting. Note that the fullBright parameter only works if r, g, b, and/or a is not equal to 1. Make sure to add the indexes of any dusts you create to Main.playerDrawDust, and the indexes of any gore you create to Main.playerDrawGore.
- ModifyDrawInfo(Terraria.ModLoader.PlayerDrawInfo@)()
- Allows you to modify the drawing parameters of the player before drawing begins.
- ModifyDrawLayers(System.Collections.Generic.List{Terraria.ModLoader.PlayerLayer})()
- Allows you to modify the drawing of the player. This is done by removing from, adding to, or rearranging the list, by setting some of the layers' visible field to false, etc.
- ModifyDrawHeadLayers(System.Collections.Generic.List{Terraria.ModLoader.PlayerHeadLayer})()
- Allows you to modify the drawing of the player head on the minimap. This is done by removing from, adding to, or rearranging the list, by setting some of the layers' visible field to false, etc.
- ModifyScreenPosition()
- Use this hook to modify Main.screenPosition after weapon zoom and camera lerp have taken place.
- ModifyZoom(System.Single@)()
- Use this to modify the zoom factor for the player. The zoom correlates to the percentage of half the screen size the zoom can reach. A value of -1 passed in means no vanilla scope is in effect. A value of 1.0 means the scope can zoom half a screen width/height away, putting the player on the edge of the game screen. Vanilla values include .8, .6666, and .5.
- PlayerConnect(Terraria.Player)()
- Called on clients when a player connects.
- PlayerDisconnect(Terraria.Player)()
- Called when a player disconnects.
- OnEnterWorld(Terraria.Player)()
- Called on the LocalPlayer when that player enters the world. SP and Client. Only called on the player who is entering. A possible use is ensuring that UI elements are reset to the configuration specified in data saved to the ModPlayer. Can also be used for informational messages.
- OnRespawn(Terraria.Player)()
- Called when a player respawns in the world.
- ShiftClickSlot(Terraria.Item[],System.Int32,System.Int32)()
- Called whenever the player shift-clicks an item slot. This can be used to override default clicking behavior (ie. selling or trashing items).