1201 LUA API

Warning

本文档不再更新,请直接参考源码中的注释。

1. 全局对象

1.1 log

不要使用 print 来打印内容。

框架提供了 log 机制,使用这个机制,可以容易实现各个级别的 log 打印,或者禁用某个级别的 log 显示。

log 提供 5 个级别,这与 Python 的 logging 包定义相同:

Logger.CRITICAL = 50    -- 危险
Logger.ERROR    = 40    -- 错误
Logger.WARNING  = 30    -- 警告
Logger.INFO     = 20    -- 信息
Logger.DEBUG    = 10    -- 调试信息
Logger.NOTSET   = 0     -- 未设置

使用 log 的时候,可以这样做:

-- 用于调试的时候显示信息,我们工作中大部分的信息都可以使用 debug 记录。
log:debug("数组长度: %d", #list)
-- 确定要显示或记录的信息。
log:info("服务器IP: %s, 端口: %d", ip, port)
-- 警告信息。
log:warning("服务器IP: %s, 端口: %d", ip, port)
-- 错误信息。一般用于可恢复的错误。
log:error("ERROR %s", str)
-- 危险信息。一般用于不可恢复的错误。
log:ctitical("ERROR %s", str)

上面的方法不但支持这样的调用::

log:debug("数组长度:%s", #list)

也同样支持这样的调用::

log:debug("数组长度:", #list)

Logger 是一个 class ,它的 new 方法支持多个参数:

  • level 用于指定一个显示级别,低于这个级别的 log 都不会被记录。
  • 后面的参数都被作为 LogHandler 的实例对待。
function Logger:ctor(level, ...)
    self:setLevel(level or Logger.NOTSET)
    self._handlers = {...}
end

log 是个 Logger 的实例,保存在全局命名空间中,在 root/pretreatment.lua 中被定义::

log = cc.log.Logger.new(cc.log.Logger.NOTSET, cc.log.PrintHandler.printHandler)

因此,记得使用 log 的时候必须用 : 而不能用 .

为了方便使用, 有一个全局方法是这样定义的:

function d(fmt, ...)
    log:debug(fmt, ...)
end

如果有些模块希望独立管理自己的 log, 则可以建立自己专用的 log 对象:

local fightlog = cc.log.Logger.new( cc.log.Logger.DEBUG,
    cc.log.PrintHandler.printHandler,
    cc.log.FileHandler.new('fightlog.txt'))

1.2 dump

dump 的签名如下

function dump(value, nesting, behavior)
    -- .....
end
  1. value 要输出的值;
  2. nesting 输出时的嵌套层级,默认为 3;
  3. behavior 值为 ‘string’ 则返回 string,为 ‘table’ 则返回包含 dump 内容的 table,为 ‘print’ 则打印 string;默认值为 ‘print’。

2. 工具类

2.1 RE

这个类文件的路径为 quick/zr/ResourceManager.lua

对应的测试 模块 位于 test/rm

2.1.1 资源类型

RM 支持的资源类型,有3种:

RM.T_ANI

动画定义文件。

RM.T_SF

帧定义文件,就是 plist。

RM.T_TEX

单张纹理,就是单张图片。

RM.T_DB

dragonbones 骨骼动画。

2.1.2 逐帧动画相关

getAni(name)

获取一个缓存中的 Animation 对象。

Parameters:name (string) – 动画的名称。 注意不是动画定义文件的名称,而是动画定义文件中定义的动画的名称。
addAniDef(aniDefName, handler)

从一个动画定义文件中载入动画配置。

Parameters:
  • aniDefName (string) –

    动画定义文件的名称,可以提供完整路径,也可以使用缩写。

    例如,对于 ani/ani_def_bullet.lua 这个定义文件,下面三个值是等价的。

    • bullet
    • ani_def_bullet
    • ani/ani_def_bullet.lua
  • handler (function) –

    载入成功后调用,接受三个参数:

    1. aniDefName,原样返回;
    2. aniDefPath,定义文件完整路径;
    3. aniDef,定义文件的 lua table。
Return type:

boolean

Returns:

若该定义文件位于缓存中则返回 true, 否则返回 false。 无论返回的值是什么,handler 都会被调用。

范例代码:

RM.addAniDef('bullet', function(defName, defPath, def)
    d('defName: %s, defPath:%s', defName, defPath)
    d('def: %s', dump(def, 5, 'string'))
end)
removeAniDef(aniDefName, removeOthersCache)

将一个动画配置文件中的所有动画从缓存中移除。

Parameters:aniDefName (string) – 动画定义文件名称,详见 addAniDef()
Parameters:removeOthersCache (boolean) – 默认为 true, 它会同时从 SpriteFrameCache 和 TextureCache 中移除对应的帧缓存和纹理缓存。
Rtypt:boolean
Returns:若该定义文件已经不再缓存中泽返回 false, 否则返回 true。
addAniDefList(list, asyncHandler)

载入一组动画定义文件到缓存中。

Parameters:list (table) – 包含定义文件的列表。其中的每项是一个 aniDefName
Parameters:asyncHandler (function) – 载入列表中的每一项载入成功,就会调用一次。接受一个参数 amount,代表剩余的载入数量。若该值小于等于0,则代表列表载入完成。
RM.addAniDefList({"bullet", "face"}, function(amount)
    d('addAniDefListHandler, amount: %d', amount)
    if amount > 0 then return end
    d('loading list done!')
end)
removeAniDefList(list, removeOthersCache)

从缓存中移除一组动画定义文件。

Parameters:

2.1.3 单张纹理相关

addTex(name, handler)

将一个纹理载入 TextureCache 中。

Parameters:
  • name (string) – 要载入的纹理路径。和 addAniDef() 不同, 纹理必须使用完整路径。例如: pdir/testbg/helloworld.png
  • handler (function) – 若提供 handler,则代表是异步载入,否则代表同步载入。 handler 接受一个参数,就是提供的纹理路径。
Return type:

boolean

Returns:

同步载入返回 true, 异步载入返回 false。

removeTex(name)

从 TextureCache 中移除名为 name 的纹理。

Parameters:name (string) – 要移除的纹理路径。
addTexList(list, asyncHandler)

将一组纹理载入 TextureCache 中。

Parameters:
  • list (table) – 待载入的纹理列表,其中每项代表一个纹理路径。 详见 addTex()
  • asyncHandler (function) – 详见: asyncHandler
removeTexList(list)

将一组纹理从 TextureCache 中移除。

Parameters:list (table) – 移除的纹理列表。

2.1.4 plist相关

addSF(name, handler)

将一个 plist 纹理集载入 SpriteFrameCache 中。

Parameters:
  • name (string) – 要载入的 plist 的名称。 和 addAniDef() 以及 addTex() 不同, 这里提供的名称必须使用完整路径。但不能提供扩展名。 例如: plst/test 代表 plst/test.pngplst/test.plist 两个文件。
  • handler (function) – 提供则代表异步载入,不提供则代表同步载入。
removeSF(name)

将一个 plist 文件里从 SpriteFrameCache 和 TextureCache 中移除。

Parameters:name (string) – 要移除的 plist 的名称。
addSFList(list, asyncHandler)

将一组 plist 纹理集载入 SpriteFrameCache 中。

Parameters:
  • list (table) – 待载入的纹理列表,其中每项代表一个 plist 纹理集路径。 详见: addSF()
  • asyncHandler (function) – 详见: asyncHandler
removeSFList(list)

将一组 plist 纹理集从 SpriteFrameCache 和 TextureCache 中移除。

Parameters:list (table) – 移除的 plist 纹理集列表。

2.1.5 骨骼动画相关

getDB(name)

获取一个新的 DBCCArmatureNode 对象。

Parameters:name (string) – 骨骼动画的名称, 就是位于 res/arm 文件夹中的子文件夹名。 例如 “1001”。
Return type:DBCCArmatureNode
Returns:一个新的 DBCCArmatureNode 实例。
addDB(name, handler)

将一个骨骼动画的所有资源载入骨骼动画缓存。

Parameters:
  • name (string) – 要载入的骨骼动画名称。参见 getDB()
  • handler (function) –

    载入成功的回调函数。 handler 有三个参数:

    1. name 提供的骨骼动画名称;
    2. armFile 根据提供的骨骼动画名称取得的骨骼动画资源路径
    3. arm 骨骼动画缓存信息。
removeDB(name)

将一个骨骼动画的资源从缓存中移除。

Parameters:name (string) – 要移除的骨骼动画名称。参见 getDB()
addDBList(list, asyncHandler)

将一组骨骼动画资源载入骨骼动画缓存。

Parameters:
  • list (table) – 待载入的骨骼动画名称列表。参见 addDB()
  • asyncHandler (function) – 详见: asyncHandler
removeDBList(list)

将一组骨骼动画资源从骨骼动画缓存中移除。

Parameters:list (table) – 待移除的骨骼动画名称列表。参见 addDB()

2.1.6 批量载入

为了简化使用,提供了批量载入命令,可以同时载入多个不同的列表。

addResourceList(asyncHandler, ...)
Parameters:
  • asyncHandler (function) –

    批量载入的回调函数。 回调函数在列表中的任何一项载入成功时都会被调用, 因此,需要判断函数的参数来了解目前的载入状态。 这个函数接受三个参数:

    1. 是否载入完成。 所有列表载入完成该值为 true,否则为 false。
    2. 当前正在载入的资源类型。见 2.1.1 资源类型
    3. 当前每种类型的载入数量。这是一个 table,键名为类型名称,键值为剩余的项的数量。
  • ... – 剩余的参数必须成对出现, 每对中的第一个值为 资源类型 , 第二个值为要载入的资源列表。

范例代码:

RM.addResourceList(function(succ, resType, amounts)
    d('addResourceHandler, succ: %s, resType: %d, \namounts: %s',
        succ, resType, amounts)
    if not succ then return end
    self:_addAni()
    self:_addPlist()
    self:_addTex()
    self:_printCachedInfo()
end,
RM.T_ANI, {'bullet'},
RM.T_SF, {'plst/test'},
RM.T_TEX, {'pdir/testbg/hellworld.png'},
RM.T_DB, {'1001'})
removeResourceList(...)
Parameters:... – 定义与 addResourceList() 相同。

2.1.7 打印 TextureCache 缓存内容

getCachedTextureInfo(fmt)

将缓存内容作为字符串获取。

Parameters:fmt (string) – 可选参数,若提供 fmt,则其中必须只能包含一个 %s , 缓存中的内容将替换这个 %s .
Return type:string.
Returns:缓存内容的字符串。
printCachedTextureInfo(fmt)

直接打印缓存内容。

Parameters:fmt (string) – 与 getCachedTextureInfo() 相同。

2.2 FU

这个类文件的路径为 quick/zr/FileUtil.lua

对C++提供的 FileUtils 进行封装。

Warning

不要使用 cc:FileUtils 中的任何方法,必须使用这里提供的方法。

WRITEABLE_PATH

这个静态变量保存了可写目录的完整路径

getWritablePath(filename)
Parameters:filename (string) – 获取一个可写路径,如果提供了 filename 参数, 返回的路径就是可写路径加上参数内容。否则直接返回可写路径。
Return type:string
Returns:一个绝对路径。
getFullPath(filename)

提供一个相对路径文件名,返回它的绝对路径。 这个文件必须相对于 res 文件夹。 若不提供值,则返回 res 文件夹的绝对路径。

Parameters:filename (string) – 相对路径。
Return type:string
Returns:一个绝对路径。
readFile(filename)

读取文件内容

Parameters:filename (string) – 相对路径。
Return type:string
Returns:文件的字符串内容。
writeFile(filename, content, mode)

写入文件内容

Parameters:
  • filename (string) – 文件名称,可以是相对或者绝对路径。
  • content (string) – 要写入的文件内容字符串。
  • mode (string) – 打开模式,默认为 w+b
Return type:

boolean

Returns:

写入成功返回 true,否则返回 false。

exists(filename)

判断文件或者文件夹是否存在。

Parameters:filaname (string) – 可以是相对或绝对路径。文件夹必须以 / 结尾。
Return type:boolean
Returns:存在返回 true,否则返回 false。
mkdir(dirname)

创建一个文件夹

Parameters:dirname (string) – 必须是绝对路径,必须以 / 结尾。
Return type:boolean
Returns:成功返回 true,否则返回 false。
rm(filename)

删除一个文件或者文件夹

Parameters:filename (string) – 必须是绝对路径。文件夹必须以 / 结尾。
Return type:boolean
Returns:成功返回 true,否则返回 false。
rename(parent, old, new)

重命名一个文件

Parameters:
  • parent (string) – 父文件夹路径,必须是绝对路径。
  • old (string) – 文件名。
  • new (string) – 新文件名。
getFileSize(filename)

获取一个文件的大小

Parameters:filename (string) – 可以是相对或者绝对路径。
Return type:number
Returns:文件大小的数字。