异星工厂 Libraries and functions

贺子昂

2023-12-01

原文地址https://lua-api.factorio.com/latest/Libraries.html
Factorio provides the Lua environment several functions and libraries that cannot be found in standard Lua 5.2.1. Furthermore, it modifies some functions to be deterministic, notably pairs() and math.random().
Factorio为Lua环境提供了一些在标准Lua 5.2.1中找不到的功能和库。此外，它修改了确定性的某些功能，尤其是pairs()和math.random()。

1. Libraries

serpent
Factorio将serpent库作为全局变量提供serpent给所有mod使用。它允许对表进行简单的调试，因为使用serpent可以轻松打印它们，例如通过使用serpent.block()。但是，serpent不能漂亮地打印LuaObjects，例如LuaEntity。
修改了serpent库以提高确定性，例如，默认情况下关闭注释以避免返回表地址。
库和功能
Factorio为Lua环境提供了一些在标准Lua 5.2.1中找不到的功能和库。此外，它修改了确定性的某些功能，尤其是pairs()和math.random()。
用法

local serpent = require("serpent")
local a = {1, nil, 3, x=1, ['true'] = 2, [not true]=3}
a[a] = a -- self-reference with a table as key and value

print(serpent.dump(a)) -- full serialization
print(serpent.line(a)) -- single line, no self-ref section
print(serpent.block(a)) -- multi-line indented, no self-ref section

local fun, err = loadstring(serpent.dump(a))
if err then error(err) end
local copy = fun()

-- or using serpent.load:
local ok, copy = serpent.load(serpent.dump(a))
print(ok and copy[3] == a[3])

2. New functions

log（）

此功能允许记录LocalisedStrings到异星工厂日志文件。结合 serpent，这使得在数据阶段的调试更加容易，因为它允许简单地检查整个原型表。例如，这允许查看硫项目原型的所有属性：

log(serpent.block(data.raw["item"]["sulfur"]))

localized_print（）

此函数允许将LocalisedStrings打印到stdout，而不会污染日志文件。这主要用于与将Factorio作为子进程启动的外部工具进行通信。

table_size（）

Factorio提供此功能table_size()作为查找具有非连续键的表大小的简单方法，由于标准方法#不适用于这些键。该函数是以下Lua代码的C ++端实现，因此它比在Lua中使用此代码更快：

  local function size(t)
    local count = 0
    for k,v in pairs(t) do
      count = count + 1
    end
    return count
  end

请注意，table_size()这对于LuaCustomTables不能正常工作，它们的大小必须由LuaCustomTable :: operator＃确定。

3.Modified functions修改功能

一些标准Lua的模块在Factorio的Lua环境中不可访问，主要是为了确保确定性。这些不可使用的模块有：loadfile()，dofile()，coroutine，io和os。Factorio提供了自己的package。

pairs()

在标准Lua中，使用时的迭代顺序pairs()是任意的。由于Factorio必须具有确定性，因此在Factorio的Lua版本中对此进行了更改。使用时next()，Factorio的迭代顺序（pairs()用于迭代）取决于插入顺序：首先插入的键先进行迭代。但是，Factorio还保证无论插入顺序如何，都从1-1024开始迭代前1024个编号的键。这意味着pairs()与ipairs()相比，通常使用中没有任何缺点。

print()

print()输出到标准输出。对于Factorio，这意味着它不会最终出现在日志文件中，因此只能在从命令行启动Factorio时读取。因此，通常更易于使用log()或使用LuaGameScript :: print进行调试。

require()

由于的更改package，功能也require()有所更改。使用绝对路径时，该路径从mod根开始，此外…还被禁用为路径变量。这意味着不可能从mod目录外部加载任意文件。但是，Factorio提供了两种从其他mod加载文件的方式：

核心mod的lualib目录包含在要检查文件的路径中，因此可以直接从那里要求文件，例如util文件：require(“util”)。
此外，还可以通过使用来要求其他mod的文件require(“mod-name.file”)。
require()不能在控制台，事件侦听器或期间使用remote.call()。该函数期望任何文件以.lua扩展名结尾。

math.random（）

math.random()可以在Factorio中实现，以便在数据阶段和运行时脚本编写过程中都具有确定性。在数据阶段，它以恒定的数字播种。在运行时脚本编写过程中，它使用地图的全局随机数生成器，该生成器以地图种子作为种子。地图的全局随机数生成器在所有mod和核心游戏之间共享，因此它们可以影响生成的随机数。如果不需要这种行为，可以使用LuaRandomGenerator来创建一个与核心游戏和其他mod完全分离的随机生成器。在运行时阶段，math.random()不能在事件外部或加载期间使用。

math.randomseed（）

math.randomseed()在Factorio中使用不会对随机数生成器产生任何影响，该函数不会执行任何操作。如果需要自定义播种或重新播种，可以使用LuaRandomGenerator代替math.random()。