饥荒联机版Mod开发——常用inst方法（八）
前言
在饥荒联机版Mod开发——Class, Prefab, component,debug（四）
中我们简单介绍了游戏实体（Entity）和组件的使用方法，在这一章里我们将学习Entity的常用方法，想了解更多也可以去看文中提到的源代码
生成实体
生成实体可分为两种情况，一种是控制台生成，另一种是代码里生成。前者是我们进游戏后调试用，后者是日常写代码时用。
控制台生成预设物实体
--consolecommands.lua
--在鼠标位置生成预设物实体，如猪人 "pigman"
function c_spawn(prefab, count=1) ... end
--给予玩家可放进物品栏的预设物实体，如树枝 "twigs"
function c_give(prefab, count=1) ... end
代码里生成预设物实体、实体
--mainfunctions.lua
--生成并返回预设物实体，一般只需要个name。如果creator没有对应皮肤，则显示默认皮肤
function SpawnPrefab(name, skin, skin_id, creator) ... end
--在原本的实体位置生成预设物实体，并删除原本的实体，一般只需要前两个参数
function ReplacePrefab(original_inst, name, skin, skin_id, creator) ... end
--生成并返回实体，name可省，常见于各prefab的fn中
function CreateEntity(name)
local ent = TheSim:CreateEntity() --C层的Entity数据，存放在inst.entity
local guid = ent:GetGUID() --GUID独一无二的标志数字
local scr = EntityScript(ent) --entityscript.lua，这就是inst
if name ~= nil then
scr.name = name
end
Ents[guid] = scr --全部Entity都放到Ents这个全局表里(声明在main.lua)
NumEnts = NumEnts + 1 --全部Entity的数量(声明在main.lua)
return scr --返回inst
end
从CreateEntity中我们可以看成，常见的 inst:XXX() 实际调用的是entityscript.lua中的方法
此外mainfunctions.lua中还定义了其他的全局函数，如
获取时间的GetTick()、
游戏开始时的Start()、保存游戏SaveGame(…)，关闭游戏Shutdown()、SaveAndShutdown()
游戏回调OnFocusLost()、OnFocusGained()、
Entity回调OnEntitySleep()，OnEntityWake，OnPhysicsWake，OnPhysicsSleep、
GUID处理函数GetEntityString等； inst.GUID
监听/推送事件
事件作为脚本中传递信息的重要途径，在降低代码复杂度，提供可扩展型上发挥着至关重要的作用。本质是把函数(fn)先存起来（ListenForEvent），在特定的时候（PushEvent）再传入参数(source, data)来调用函数(fn)。
--entityscript.lua
--监听/取消监听事件
--event：string，独一无二的事件名，对应inst:PushEvent中的event
--fn：监听的函数，参数是 (source, data)，source对应调用PushEvent的Entity，data对应PushEvent时的data，也可以print出来看看data是什么
--source：被监听的实体，默认监听自身
inst:ListenForEvent(event, fn, source=inst)
inst:RemoveEventCallback(event, fn, source=inst)
inst:RemoveAllEventCallbacks()
--推送事件，运行fn
--event：string，独一无二的事件名，mod的event推荐加个前缀
--data：any，一般是个table
--如果inst有sg（stategraph状态图）且sg在监听这个事件，也会调用 inst.sg:PushEvent(event, data)
--如果inst有brain（大脑/AI）也会调用 inst.brain:PushEvent(event, data)
inst:PushEvent(event, data)
--table的key可以是任意非nil值，通过table[key]来访问，key是字符串时可以写成table.key
--当前source被监听的事件列表 source.event_listeners[event][inst] = {fn1, fn2, ...}
--当前inst在监听的事件列表 inst.event_listening[event][source] = {fn1, fn2, ...}
在监听世界(TheWorld)时，可以把source赋值为TheWorld。不过如果要监听世界的状态(worldstate)（时间，洞穴时间，月圆，天气，季节，温度，湿度，下雪，下雨等）
更推荐使用下面的函数
--entityscript.lua
--TheWorld的预设物在prefabs/world.lua
--监听/取消监听世界TheWorld.state中的状态 （components/worldstate）
--var：components/worldstate.lua中 SetVariable(var, val, togglename)
--fn：一般参数为(inst, val)，不过start或stop开头的var，只有inst。
inst:WatchWorldState(var, fn)
inst:StopWatchingWorldState(var, fn)
inst:StopAllWatchingWorldStates()
--inst.worldstatewatching[var] = {fn1, fn2, ...}
--_watchers[var][inst] = { {fn, inst}, ... }
--举个例子components/worldstate.lua中
--SetVariable(var, val, togglename)
--有第三个参数时，有start和stop开头var (val and "start" or "stop")..togglename
SetVariable("cavephase", phase)
--> var="cavephase", fn的val=phase，洞穴白天到黄昏等时期变化时推送
SetVariable("iscaveday", phase == "day", "caveday")
--> var="iscaveday" fn第二个参数val=(phase == "day")，一个boolean
--> var="startcaveday"，val为true时推送，fn参数只有inst
--> var="stopcavaday"，val为false时推送，fn参数只有inst
注：
扫描二维码关注公众号，回复：
15555834 查看本文章
- TheWorld是Entity，赋值在prefabs/world.lua，负责管理世界、地图、时钟、玩家生成等。
- 判断是否是地下世界，TheWorld:HasTag(“cave”)
- The开头及Ents等全局变量(声明在main.lua)，可以在游戏中直接访问到
- 在modmain中也可以访问到main中的全局变量，不过直接访问时可能还没赋值，所以一般写在
AddGamePostInit(fn()) --先
AddSimPostInit(fn()) --后，和单机不同，fn没有参数，ThePlayer也没赋值
如果需要访问ThePlayer，用下面函数
AddPlayerPostInit(fn(player)) --在fn中用ThePlayer==player来判断是否当前玩家
使用标签
标签常用于Component判断Entity，也影响着生物的AI等。
_开头的标签比较特殊，在下面的组件部分介绍。
常见的tags如下：
- NOCLICK：不可点击物体
- FX：特效
- lightningtarget：闪电目标（移除就不不会被雷劈）
- electricdamageimmune：电伤害免疫（机器人免疫电伤害）
- irreplaceable：无法替代，玩家离开世界自动掉落（眼骨等）
- player、playerghost：玩家状态（也可以用inst.components.health:IsDead()来判断）
- scarytoprey：吓跑小动物（移除就不会吓跑小动物）
--tag: string
inst:AddTag(tag)
inst:RemoveTag(tag)
inst:HasTag(tag)
--tags = {"tag1", "tag2", ...}
inst:HasTags(tags) --拥有全部
inst:HasOneOfTags(tags) --拥有其中一个标签
增删组件
--name：string, 对应components中文件夹中的文件名，组件的使用看第四章
inst:AddComponent(name) --有_replica的同名组件会自动添加（服务器）
inst:RemoveComponent(name)
--inst.components.name
--inst.repica.name
网络组件
以_replica的结尾同名组件 ，用网络变量(netvars.lua)进行服务器和客户端之间的通信，需要服务器和客户端都添加以_replica的结尾同名组件。
这里先讲下添加组件流程，具体使用以后出个网络通信相关的教程，感兴趣的也可以先去看
官方的netvars教程
注：动作的网络变量了entityscript.lua的AddNetwork()，其他的大部分在player_classified.lua
以玩家的health组件为例子（服务器修改血量，通知）
local inst = CreateEntity()
inst.entity:AddNetwork() --网络通信当然要添加网络了
inst:AddTag("_health") --添加网络组件标签
inst.entity:SetPristine() --客户端根据添加的_开头的tag，添加xxx_replica组件
if not TheWorld.ismastersim then return inst end --客户端返回，下面是仅服务器代码
inst:RemoveTag("_health") --移除网络组件标签，等AddComponent会再次加上。官方书写习惯，不删问题应该也不大
inst:AddComponent("health") --服务器添加health和health_replica组件，和_health标签。
--注：客户端只需要知道玩家的血量，其他生物的血量并不需要知道，所以其他生物的预设物fn中
--并不会有inst:AddTag("_health") 和 inst:RemoveTag("_health") 这两句
定时/阶段任务
--entityscript.lua scheduler.lua
--下面4个函数的返回值都是Periodic 可通过 :Cancel() 取消任务
--定时任务，time秒后调用 fn(inst, ...)。仅调用一次，不需要手动取消
--注：inst:DoTaskInTime(0,...) 时会在下一帧调用； Sprite中是毫秒
inst:DoTaskInTime(time, fn, ...)
--阶段任务，initialdelay秒后调用fn(inst, ...)，之后每隔time秒调用一次fn，需要手动取消
--一般都是 inst.task = inst:DoPeriodicTask(...)，某个时候 inst.task:Cancel()
inst:DoPeriodicTask(time, fn, initialdelay=time, ...)
--和上面的类似，不过定时不受世界暂停时影响
inst:DoStaticTaskInTime(time, fn, ...)
inst:DoStaticPeriodicTask(time, fn, initialdelay, ...)
inst:CancelAllPendingTasks() --取消上面所以的定时任务
回调函数
-------- entityscript.lua---------
Fn：对应函数 XXXCb：回调函数，非nil时调用
一般都是先调用ComponentCb，之后再调用EntityCb，除非是Pre开头的
EntityCb常规写法： inst.OnXXX = function(inst, …) … end
ComponentCb常规写法：function Cmpname:OnXXX(…) … end
- refs：引用的Entity列表或nil，{Entity1, Entity2, …}
- cmpdata：一般是个table，仅保存数值，不保存引用
- newents：重新开服时生成的Entitys，一般用不上
- builder：一般是玩家的Entity
- dt：deltatime，距离上次更新的时间
| Fn | EntityCb | ComponentCb |
|---|---|---|
| inst:GetPersistData() | inst:OnSave(data) -> refs | cmp:OnSave() -> cmpdata, refs |
| inst:SetPersistData(data, newents) | inst:OnPreLoad(data, newents) inst:OnLoad(data, newents) | cmp:OnLoad(cmpdata, newents) |
| inst:LoadPostPass(newents, savedata) | inst:OnLoadPostPass(newents, savedata) | cmp:LoadPostPass(newents, cmpdata) |
| inst:OnBuilt(builder) | inst:OnBuiltFn(builder) | cmp:OnBuilt(builder) |
| inst:Remove() | inst:OnRemoveEntity() | cmp:OnRemoveEntity() |
| inst:LongUpdate(dt) | inst:OnLongUpdate(dt) | cmp:LongUpdate(dt) |
--------Update：update.lua--------
dt: deltatime，距离上次更新的时间
- WallUpdate：墙壁更新
- Update：日常更新
- StaticUpdate：世界暂停时开始更新
- LongUpdate：长时间间隔的更新，如进出洞穴，跳天数等
| Fn | EntityCb | ComponentCb |
|---|---|---|
| WallUpdate(dt) | - | cmp:OnWallUpdate(dt) |
| Update(dt) | - | cmp:OnUpdate(dt) |
| StaticUpdate(dt) | - | cmp:OnStaticUpdate(0) |
| LongUpdate(dt, ignore_player) | inst:OnLongUpdate(dt) | cmp:LongUpdate(dt) |
--------Player：player_common.lua-----------.
玩家特有回调
inst.OnNewSpawn = function() … end
inst.OnDespawn = function() … end
父子实体
--entityscript.lua
--child：Entity
inst:AddChild(child)
inst:RemoveChild(child)
--inst.children[child] = true
--child.parent = inst child.platform = nil
平台
当前只用在船上，让玩家随船移动
--entityscript.lua
--child: Entity
inst:AddPlatformFollower(child)
inst:RemovePlatformFollower(child)
inst:GetPlatformFollowers()
inst:GetCurrentPlatform()
--inst.platformfollowers[child] = true
--child.platform = inst child.parent = nil
删除
--移除自身和子Entity，从父Entity的孩子中移除
--触发事件onremove，OnRemoveEntity回调
--移除所以监听、组件、定时和阶段任务
inst:Remove()
inst:IsValid() --正常返true，被Remove返false
位置，角度
inst:GetPosition() --> Point(inst.Transform:GetWorldPosition()) 一个table
inst:GetRotation() --> inst.Transform:GetRotation()
inst:FacePoint(x, y, z) --> 面向某点
inst:ForceFacePoint(x, y, z) --> 强制面向某点
inst:FaceAwayFromPoint(dest, force)
--DistanceSq: 距离的平方，少了sqrt，减少计算量
inst:GetDistanceSqToInst(inst) --> 距离的平方
inst:IsNear(otherinst, dist) --> inst:GetDistanceSqToInst(otherinst) < dist*dist
inst:GetDistanceSqToPoint(x, y, z) --> 距离的平方
inst:IsNearPlayer(range, isalive) --> range半径内是否有玩家
inst:GetNearestPlayer(isalive) --> 最近的玩家
inst:GetDistanceSqToClosestPlayer(isalive) --> 距离最近的玩家的距离的平方
显示/隐藏
--显示/隐藏，仅改变显示
inst:Show()
inst:Hide()
--显示到屏幕，常用于物品被移出物品栏
--IsInLimbo()->false inst:Show()
--开始brain,sg,Physics,Light,AnimState,DynamicShadow,MiniMapEntity
--inst:PushEvent("exitlimbo")
inst:ReturnToScene()
--从屏幕隐藏中，常用物品被放进物品栏
--IsInLimbo()->true inst:Hide()
--停止brain,sg,Physics,Light,AnimState,DynamicShadow,MiniMapEntity
--inst:PushEvent("enterlimbo")
inst::RemoveFromScene()
判断
inst:IsOnWater() --是否在水上，即没船且脚下是海
inst:IsInLimbo() --是否在物品栏，仅在mastersim（服务器）有效，客户端用INLIMBO标签判断？
inst:GetIsWet() --是否是湿的，服务器客户端都可以使用
inst:IsInLight() --是否在光照内
inst:IsValid() --正常返true，被Remove返false
大脑
--brainfn: require("brains/xxxbrain")
inst:SetBrain(brainfn)
inst:StopBrain()
inst:RestartBrain()
状态图
--name: "SGXXX" stategraphs文件夹下的文件名
inst:SetStateGraph(name)
inst:ClearStateGraph()
皮肤
--entityscript.lua
inst:GetSkinBuild()
inst:GetSkinName()
--inst.AnimState:SetSkin(build_name, def_build)
地图
--entityscript.lua
--设置参数，具体应用在components/map.lua
inst:SetDeployExtraSpacing(spacing)
inst:SetTerraformExtraSpacing(spacing)
inst:SetGroundTargetBlockerRadius(radius)
inst:IsOnValidGround() --是否在地面上
inst:IsOnOcean(allow_boats) --是否在海上
inst:IsOnPassablePoint(include_water, floating_platforms_are_not_passable) --是否可通过某点
inst:GetCurrentTileType() --获得当前地皮，如果要获得有效地皮先判断inst:IsOnValidGround()
物理
设置物理的时候，一般用的是 standardcomponents.lua 里的 MakeXXXPhysics，不过偶尔有需要重新设置物理碰撞半径的时候
--entityscript.lua
inst:SetPhysicsRadiusOverride(radius) --设置覆盖的物理碰撞半径
inst:GetPhysicsRadius(default) --返回物理碰撞半径或default