客户端组件类扩展 ^1.3.0

客户端实体组件用于把一段客户端逻辑绑定到实体生命周期上。它和服务端组件共享大部分 QBaseEntityComp 接口，但实体内存状态、可见范围和自动释放时机都以客户端渲染视野为准。

from .QuModLibs.Modules.EntityComps.Client import QBaseEntityComp

更新入口建议

客户端组件推荐优先使用 onGameTick() 编写稳定业务逻辑。update() 会经过 getNeedUpdate() 判定；虽然客户端默认实现通常会继续放行，但该入口语义仍取决于 API 内部实现和组件覆写逻辑，不建议把它当作固定逻辑帧。

基本用法

# -*- coding: utf-8 -*-
from .QuModLibs.Client import *
from .QuModLibs.Modules.EntityComps.Client import QBaseEntityComp

class ClientMarkComp(QBaseEntityComp):
    def __init__(self):
        QBaseEntityComp.__init__(self)
        self.tickCount = 0

    def onBind(self):
        QBaseEntityComp.onBind(self)
        print("客户端组件绑定: {}".format(self.entityId))

    def onGameTick(self):
        QBaseEntityComp.onGameTick(self)
        self.tickCount += 1
        # 推荐将稳定的客户端逻辑写在这里。

    def onUnBind(self):
        QBaseEntityComp.onUnBind(self)
        print("客户端组件释放: {}".format(self.getUnBindINFO()))

@Listen("AddEntityClientEvent")
def AddEntityClientEvent(args={}):
    comp = ClientMarkComp()
    comp.bind(args["id"])

按实体类型自动绑定

客户端也支持通过 regEntity 为指定实体类型注册默认组件。当客户端收到 AddEntityClientEvent 且实体类型匹配时，会自动构造并绑定组件。

from .QuModLibs.Modules.EntityComps.Client import QBaseEntityComp

@QBaseEntityComp.regEntity("minecraft:zombie", "minecraft:husk")
class ZombieClientComp(QBaseEntityComp):
    def onBind(self):
        QBaseEntityComp.onBind(self)
        # 此时 self.entityObj 可用于客户端实体操作。
        ...

生命周期差异

客户端组件跟随客户端实体内存状态：

• 实体进入客户端渲染视野时，通常会触发 AddEntityClientEvent，可创建或自动绑定组件。
• 实体离开客户端渲染视野、被移除或客户端关闭时，会释放运行时组件。
• 客户端组件只适合处理表现层、UI、特效、模型显示等客户端逻辑；权威游戏逻辑仍应放在服务端组件中。

获取与移除组件

客户端 QBaseEntityComp 提供和服务端一致的常用组件访问方法：

ClientMarkComp.getComp(entityId)
ClientMarkComp.getSubComp(entityId)
ClientMarkComp.getComps(entityId)
ClientMarkComp.getSubComps(entityId)
ClientMarkComp.getTempSubComp(entityId)

ClientMarkComp.removeComp(entityId)
ClientMarkComp.removeAllComps(entityId)

EntityCacheData

EntityCacheData 是客户端实体运行时缓存组件，用于给实体临时挂载一张缓存表。缓存表为空时，组件会在定时检查后自动解绑。

from .QuModLibs.Modules.EntityComps.Client import EntityCacheData

cacheMap = EntityCacheData.getCacheMap(entityId)
cacheMap["mark_color"] = (1.0, 0.0, 0.0)

注意事项

EntityCacheData 是运行时缓存，不是持久化存储。实体离开客户端内存状态后，缓存会随组件释放。