Skip to content

Old Documentation Lua

Jump to bottom
Pychnight edited this page Feb 5, 2018 · 1 revision

Conditions

utils.lua mostly contains spawning and replacement-related utility functions. These are the available conditions:

  • Spawn/replacement requirements:
    • AfterAnyMechBoss()
    • AfterGolem()
    • AfterMoonLord()
    • AfterPlantera()
    • CustomIDContains(txt)
    • NameContains()
  • Spawn/replacement conditions:
    • DuringBloodMoon()
    • DuringDay()
    • DuringEclipse()
    • DuringFrostMoon()
    • DuringHardmode()
    • DuringNight()
    • DuringPumpkinMoon()
    • DuringRain()
    • DuringSlimeRain()
  • Spawn level:
    • AtCavernLevel(player)
    • AtSkyLevel(player)
    • AtSurfaceLevel(player)
    • AtUndergroundLevel(player)
    • AtUnderworldLevel(player)
  • Spawn areas:
    • AroundRegion(x, y, name)
    • InAndAroundRegion(player, x, y, name)
    • InBeach(player)
    • InCorruption(player)
    • InCrimson(player)
    • InDesert(player)
    • InDungeon(player)
    • InForest(player)
    • InGlowshroom(player)
    • InHallow(player)
    • InIce(player)
    • InRegion(player, name)
    • InJungle(player)
    • InMeteor(player)
  • Replacement conditions:
    • IsType(baseNpc, type)

Lua Scripting

Create a file with the following text, and name it example.lua:

require "npcs/utils"

OnAiUpdate = function(npc)
    npc:Periodically(0, function()
        npc:TargetClosestPlayer()
        local target = npc.Target
        if target ~= nil and npc:HasLineOfSight(target.TPlayer.position) then
            npc:ShootProjectileAt(target.TPlayer.position, 100, 5, 5, 0)
        end
    end, 60)
    return false
end

OnCheckReplace = function(baseNpc)
    return IsType(baseNpc, 1) and 0.10 or 0.0
end

OnCheckSpawn = function(player, x, y)
    return (DuringDay() and InRegion(x, y, "test")) and 1 or 0
end

OnCollision = function(npc, player)
end

OnKilled = function(npc)
    if RandomDouble() < 0.35 then
        SpawnCustomNpc("example", npc.Position + Vector2(-10, 0))
        SpawnCustomNpc("example", npc.Position + Vector2(0, -10))
        SpawnCustomNpc("example", npc.Position + Vector2(10, 0))
        Broadcast("Muahahaha, I still live!", Color.Crimson)
    else
        Broadcast("No! I failed to multiply!", Color.Crimson)
    end
end

OnSpawn = function(npc)
    Broadcast("Muahahaha, I have spawned!", Color.Crimson)
	return true
end

OnStrike = function(npc, player, damage, knockback, critical)
	return false
end

Now, set LuaPath above to example.lua, ShouldSpawn to true, and ShouldReplace to true. We'll go over each of the things in the file.

ALL Conditions below can be used ether for custom npcs or custom projectiles

when using it for projectiles for replace 'npc' with 'projectile'

OnAiUpdate

You can set OnAiUpdate to a function with parameters npc that returns a boolean value. Whenever the server performs an AI update on the custom NPC, this function will be called. If the function returns true, then the normal AI code will not run.

In our example Lua file, the custom NPC will periodically shoot a laser at the closest player.

  • npc: The CustomNpc that is being updated.

OnCheckReplace

If ShouldReplace is true, you can set OnCheckReplace to a function with parameters baseNpc that returns a double from 0.0 to 1.0. Whenever the server spawns a normal NPC, it will check all custom NPCs to see if they can replace the normal NPC.

In our example Lua file, the custom NPC will check if the normal NPC is a blue slime. If so, then it will assign a 0.10 chance of turning the blue slime into the custom NPC.

  • baseNpc: An NPC object that represents the normal NPC that may be replaced.

OnCheckSpawn

If ShouldSpawn is true, you can set OnCheckSpawn to a function with parameters player, x, y that returns a positive integer. Whenever the server goes to spawn NPCs at a certain location and player, it will check all custom NPCs to see if they can spawn. NOTE: Custom NPC spawning is separate from normal NPC spawning.

In our example Lua file, the custom NPC will check if it is daytime and in the TShock region test. If so, then it will assign a weight of 1 to spawning. If this custom NPC is the only NPC allowed to spawn, then it will be guaranteed to spawn if the spawn cycle allows it.

  • player: The TSPlayer that is currently spawning NPCs.
  • x: The tile X coordinate.
  • y: The tile Y coordinate.

OnCollision

You can set OnCollision to a function with parameters npc, player. Whenever a player touches the custom NPC, this function will be called. You can, for example, the debuff the player.

  • npc: The CustomNpc that collided with the player.
  • player: The TSPlayer that collided with the NPC.

OnTileCollision

You can set OnTileCollision to a function with parameters npc. Whenever a npc touches any valid tile, liquid or background tile, this function will be called. You can, for example, the debuff the player.

  • npc: The CustomNpc that collided with the tile.

OnKilled

You can set OnKilled to a function with parameters npc. Whenever the custom NPC is killed, this function will be called. You can, for example, have a custom death message.

  • npc: The CustomNpc that was killed.

OnSpawn

You can set OnSpawn to a function with parameters npc. Whenever the custom NPC is spawned, this function will be called. You can, for example, have a custom summon message.

  • npc: The CustomNpc that was spawned.

OnStrike

You can set OnStrike to a function with parameters npc, player, damage, knockback, critical that returns a boolean. Whenever a player strikes the custom NPC, this function will be called with the relevant arguments. If the function returns true, then the strike will be ignored. You can, for example, push a player away in SSC mode.

  • npc: The CustomNpc that is being struck.
  • player: The TSPlayer that struck the NPC.
  • damage: The damage.
  • knockback: The knockback.
  • critical: A boolean indicating whether the hit was critical.

CustomNpc

The CustomNpc object contains most of the properties and functions you'll need when creating a custom NPC. We'll go over them here.

Hp: int

Gets or sets the HP of the custom NPC. This can be useful if you want to heal the custom NPC on colliding with a player:

OnCollision = function(npc, player)
    npc.Hp = npc.Hp + 200
    npc.Hp = math.min(npc.Hp, 1000)
    npc.SendNetUpdate = true
    
    CreateCombatText("200", Color.LimeGreen, npc.Position)
end

Index: int

Gets the custom NPC index. This is only necessary for advanced manipulation of the NPC.

Npc: NPC

Gets the wrapped normal NPC. This is only necessary for advanced manipulation of the NPC.

Position: Vector2

Gets or sets the position of the NPC. Normally, you wouldn't want to set the position directly, but would instead teleport the NPC with Teleport.

SendNetUpdate: boolean

Gets or sets a value indicating whether to send a network update for the NPC. This is necessary if one of its values changed programatically and players haven't been informed of the change.

Target: TSPlayer (can be nil)

Gets or sets the target of the NPC. This is useful for firing projectiles at a player.

OnAiUpdate = function(npc)
    npc:Periodically(0, function()
        npc:TargetClosestPlayer()
        local target = npc.Target
        local position = target.TPlayer.position + target.TPlayer.velocity * 5
        if target ~= nil and npc:HasLineOfSight(position) then
            npc:ShootProjectileAt(position, 100, 5, 5, 0)
            npc:ShootProjectileAt(position + Vector2(25, 0), 100, 5, 5, 0)
            npc:ShootProjectileAt(position + Vector2(0, 25), 100, 5, 5, 0)
            npc:ShootProjectileAt(position + Vector2(-25, 0), 100, 5, 5, 0)
            npc:ShootProjectileAt(position + Vector2(0, -25), 100, 5, 5, 0)
        end
    end, 60)
    return false
end

Velocity: Vector2

Gets or sets the velocity of the NPC. If modifying the velocity, make sure to send a network update with SendNetUpdate.

OnCollision = function(npc, player)
    npc.Velocity = Vector2(0, -100)
    npc.SendNetUpdate = true
    player:SendInfoMessage("You can't touch me!")
end

BuffNearbyPlayers(type: int, seconds: int, tileRadius: int = 50)

Buffs nearby players within the specified tile radius.

OnKilled = function(npc)
    npc:BuffNearbyPlayers(164, 60)
    npc:MessageNearbyPlayers("As a parting gift... enjoy this.", Color.Crimson)
end

CustomTransform(name: string)

Transforms the custom NPC into the custom NPC with the specified name.

OnAiUpdate = function(npc)
    if npc.Hp < 200 then
        npc:CustomTransform("example2")
        npc:MessageNearbyPlayers("And now... you will see my true form...", Color.Crimson)
    end
    return false
end

ForEachNearbyPlayer(callback: function, tileRadius: int = 50)

Applies the callback to each nearby player within the tile radius.

GetVariable(name: string, defaultValue: object = nil) : object

Gets the stored variable attached to the custom NPC. Useful for custom logic.

HasLineOfSight(position: Vector2) : boolean

Determines whether the custom NPC has line of sight with the specified position. Useful for only firing at players if the NPC can see them.

HasVariable(name: string) : boolean

Determines whether the stored variable attached to the custom NPC exists. Useful for custom logic.

MessageNearbyPlayers(message: string, color: Color, tileRadius: int = 50)

Messages nearby players within the specified tile radius.

OnlyOnce(key: int, callback: function)

Ensures that the callback is run only once. NOTE: Every time you use this method, you must supply a different key!

OnAiUpdate = function(npc)
    if npc.Hp < 200 then
        npc:OnlyOnce(0, function()
            npc:MessageNearbyPlayers("Looks like I'm almost dead... here's a present for you.", Color.Crimson)
            SpawnCustomNpc("example2", npc.Position - Vector2(100, 0))
            SpawnCustomNpc("example2", npc.Position + Vector2(100, 0))
        end)
    end
    return false
end

Periodically(key: int, callback: function, period: int)

Periodically calls the callback with the specified period. NOTE: Every time you use this method, you must supply a different key!

OnAiUpdate = function(npc)
    npc:Periodically(0, function()
        npc:TargetClosestPlayer()
        local target = npc.Target
        local position = target.TPlayer.position
        if target ~= nil and npc:HasLineOfSight(position) then
            npc:ShootProjectileAt(position, 100, 5, 5, 0)
        end
    end, 60) -- Every 60 ticks
    return false
end

SetVariable(name: string, value: object)

Sets the variable with the specified name.

ShootProjectileAt(position: Vector2, type: int, damage: int, speed: float, knockback: float)

Shoots a projectile at the specified position. The speeds will be calculated automatically.

ShootCustomProjectileAt(position: targetVector,"projectile-name", speed, offsetVector)

TargetClosestPlayer()

Targets the closest player.

Teleport(position: Vector2)

Teleports the custom NPC to the specified position. This will display a teleportation effect, and is therefore better than just setting the position.

NpcFunctions

Also available are the following global functions:

Broadcast(message: string, color: Color)

Broadcasts a message to the entire server.

CreateCombatText(text: string, color: Color, position: Vector2)

Creates a combat text with the custom string centered on the position. This is good for nice display of miscellaneous things.

FindCustomNpcs(name: string) : CustomNpc[]

Finds all custom NPCs with the specified internal name.

FindNpcs(name: string) : NPC[]

Finds all normal NPCs with the specified name.

GetRegion(name: string)

Gets the region with the specified name.

GetTile(x: int, y: int)

Gets the tile at the specified location.

RandomDouble() : double

Returns a random double.

RandomInt(min: int, max: int) : int

Returns a random integer in the range.

SpawnCustomNpc(name: string, position: Vector2) : CustomNpc

Spawns a custom NPC with the specified internal name, and return the CustomNpc object. This is good for keeping track of spawned NPCs.

SpawnNpc(nameOrType: string, position: Vector2) : NPC

Spawns a normal NPC with the specified name or type, and return the NPC object. This is good for keeping track of spawned NPCs.

KillTile(x,y) - removes tile

Kills the Tile at the 'x,y' location

RadialKillTile(x,y,radius)

removes tiles within radius of 'x,y'

SetTile(x,y,type)

sets tile to 'type' at 'x,y' location

RadialSetTile(x,y,radius,type)

sets tiles within radius of 'x,y' to 'type'

RadialDamagePlayer(x,y,radius,damage,falloff)

damages all players within radius of 'x,y' Falloff is linear from 'x,y' to radius. Set to 0 to turn off damage falloff.

Extra tile helper functionaly, might have some use.

world coords to tile coords

TileX(worldX) TileY(worldY)

tile coords to world coords

WorldX(tileX) WorldY(tileY)

Clone this wiki locally