AFN 高级频段网络
模组知识库

参数：name 可选 string。返回：bridge, peripheral_name。查找本身不调用受保护方法，因此不检查读取权限或准入条件；返回的代理方法仍要求 ComputerID 通过当前准入条件并具有对应权限。

成功

local bridge, name = afn.find("left")
print(name)
-- bridge.listChannels() 还需要通过准入 + 开启读取权限

失败

local ok, err = pcall(afn.find, "missing")
if not ok then printError(err) end
-- no AFN bridge named missing

返回：按配置顺序排列的快照数组。需要读取权限。新字段包含 schema_version,primary_frequency,secondary_mode,secondary_frequency,value_present,value_kind,channel_value,value_revision,synaxis_activation；旧 type/subtype/value/attach_auth 仅为兼容投影。

成功

for _, c in ipairs(afn.channels()) do
  print(c.name, c.primary_frequency, c.value_present, c.strength)
end

失败

local ok, err = pcall(afn.channels)
if not ok then printError(err) end
-- computer read access is disabled...

返回：string 数组。红石、CC 或 Synaxis 任一来源有效即算激活；需要读取权限。

成功

for _, n in ipairs(afn.active()) do print("active", n) end

失败

local ok, err = pcall(afn.active, "missing")
if not ok then printError(err) end

返回：被明确设为展示的信道名数组；需要读取权限。激活状态不会改变此清单。

成功

print(textutils.serialize(afn.display_channels("left")))

失败

local ok, err = pcall(afn.display_channels, 123)
if not ok then printError(err) end
-- bridge name must be a string

参数：信道名称。返回：完整快照；不存在为 nil。需要读取权限。

成功

local c = assert(afn.get("boiler"))
print(c.primary_frequency, c.value_present, c.synaxis_receive.enabled)

失败

assert(afn.get("no_such_channel") == nil)

返回：{receive_enabled,active,strength,displayed,value_present,value_kind,revision}，同时保留旧 type/subtype 投影；不存在为 nil。需要读取权限。

成功

local s = assert(afn.state("boiler"))
print(s.active, s.strength)

失败

local ok, err = pcall(afn.state, "boiler", "missing")
if not ok then printError(err) end

读取权限返回 {present,kind,value,revision}；信道不存在才返回 nil。present=false 时 value="" 只是 CC 表占位，不能当成空文本；是否有值必须看 present。

local v = assert(afn.value("door"))
if not v.present then
  print("没有值，版本", v.revision)
elseif v.kind == "text" and v.value == "" then
  print("这是存在的空文本")
else
  print(v.kind, textutils.serialize(v.value))
end

参数、权限和返回值与 afn.value 完全相同。

local v = afn.channel_value("door")
print(v and v.present)

读取权限返回 {primary,secondary_mode,secondary_frequency,attach_auth}；信道不存在返回 nil。attach_auth 是兼容投影，新程序应看 secondary_mode。

local f = assert(afn.frequency("door"))
print("主频", f.primary)
print("副频模式", f.secondary_mode)

兼容接口有值时返回 {value,subtype,revision}，无值或信道不存在时返回 nil。它无法区分“不存在的信道”和“存在但无值”，新程序应使用 afn.value。

local legacy = afn.information("notice")
if legacy then print(legacy.subtype, legacy.value) end

返回：错误 string；正常、未知信道或无错误为 nil。典型值：invalid_frequency_or_auth、wireless_unavailable。

成功

local err = afn.last_error("secure_gate")
if err then printError(err) end

失败

local ok, err = pcall(afn.last_error, "secure_gate")
if not ok then printError(err) end -- 读取权限关闭

返回：名称；展示清单为空时 nil。需要读取权限。

成功

print(afn.get_display_channel() or "standby")

失败

local ok, err = pcall(afn.get_display_channel, "missing")
if not ok then printError(err) end

返回：boolean。切换 CRT 不激活、不停止、不修改信道；需要读取权限。

成功

assert(afn.set_display_channel("notice"))

失败

local ok = afn.set_display_channel("hidden")
if not ok then printError("not in display list") end

返回：切换后的名称；空清单为 nil。需要读取权限。

成功

print(afn.next_display_channel() or "standby")

失败

local ok, err = pcall(afn.next_display_channel)
if not ok then printError(err) end

返回：切换后的名称；空清单为 nil。需要读取权限。

成功

print(afn.previous_display_channel("left") or "standby")

失败

local ok, err = pcall(afn.previous_display_channel, false)
if not ok then printError(err) end

参数：strength 1～15，默认 15。返回：{success,error,active,strength}。需要激活权限。

成功

local r = afn.set("yard_gate", 12)
assert(r.success, r.error)

失败

local r = afn.set("missing", 15)
print(r.success, r.error) -- false unknown_channel

strength 默认 15；ticks 默认 20。到期自动清理并可产生 timeout 事件。

成功

local r = afn.pulse("bell", 15, 40)
assert(r.success, r.error)

失败

local ok, err = pcall(afn.pulse, "bell", 15, 1201)
if not ok then printError(err) end

不会清除其他电脑、红石或 Synaxis 来源。返回动作结果；需要激活权限。

成功

local r = afn.toggle("maintenance", 8)
print(r.success, r.active)

失败

local r = afn.toggle("missing", 8)
print(r.error) -- unknown_channel

ComputerID 仍获准时，这是不要求激活权限的故障安全清理；其他来源不受影响。安装鉴权板后移出白名单会由桥接器自动清除该电脑的租约。返回动作结果。

成功

assert(afn.clear("yard_gate").success)

失败

local r = afn.clear("missing")
print(r.error) -- unknown_channel

清除 CC、红石和 Synaxis 租约；需要配置权限。返回动作结果。

成功

assert(afn.clear_all("emergency").success)

失败

local ok, err = pcall(afn.clear_all, "emergency")
if not ok then printError(err) end -- configuration disabled

配置权限接受文本、布尔、有限 number 或 1～7 项连续有限数字数组。文本最多 1024 个 Unicode 码点且不超过 4096 UTF-8 字节。写值不激活；简单覆盖不必传 revision。

assert(afn.set_value("notice", "列车即将进站").success)
assert(afn.set_value("door_open", true).success)
assert(afn.set_value("pose", {12.5, 64, -8, 0, 0, 0, 1}).success)
assert(afn.set_value("blank", "").success) -- 存在的空文本

空数组、稀疏表、NaN、无穷大或超过 7 项会整次拒绝。需要防覆盖时先用 value 读取 revision，再作为第三个参数提交。

参数、权限、校验和返回值与 set_value 相同。

assert(afn.set_channel_value("counter", 42).success)

配置权限清除值但保留单调 revision；它不同于写入空文本。可选 revision 用于防止并发覆盖。

local old = assert(afn.value("notice"))
local r = afn.clear_value("notice", old.revision)
assert(r.success, r.error)
assert(afn.value("notice").present == false)

参数和行为与 clear_value 相同。

assert(afn.clear_channel_value("notice").success)

兼容接口映射到统一值写入；名称无法表达“主频和值可以共存”。新程序应使用 set_value。

兼容写法

local result = afn.set_information("notice", "列车即将进站")
assert(result.success, result.error)

这段兼容代码仍会直接覆盖 notice 的值，但新代码请改为 afn.set_value("notice", "内容", nil, "left")。

相关：统一值写入 · 统一值读取 · revision

配置权限频段必须是合法表达式；传空字符串可让信道退出无线网络，但不会删除值、屏幕设置或端口。

assert(afn.set_primary_frequency("door", "factory.door.*").success)
assert(afn.set_primary_frequency("local_note", "").success)

配置权限mode 为 none、manual 或 auth。只有 manual 必须提供合法 frequency；auth 只使用桥接器当前有效鉴权板，Lua 不能提交隐藏身份。

assert(afn.set_secondary("door", "manual", "station.public").success)
assert(afn.set_secondary("secure", "auth").success)
assert(afn.set_secondary("local", "none").success)

返回：boolean。目标必须存在；需要配置权限。展示状态不影响信道收发或激活。

成功

assert(afn.set_channel_displayed("notice", true))

失败

assert(not afn.set_channel_displayed("missing", true))

names 是连续数组，可为空；名称必须存在且不重复。返回 boolean；需要配置权限。清单外的信道即使激活也不会自动显示。

成功

assert(afn.set_display_channels({"notice", "boiler", "gate"}))

失败

assert(not afn.set_display_channels({"boiler", "boiler"}))
-- 失败时旧清单完整保留

新字段为 name,primary_frequency,secondary_mode,secondary_frequency,value_present,value_kind,channel_value,receive_enabled,displayed。主频和值都可省略；若 value_present=true 必须同时给 channel_value。新信道默认允许收发并展示；receive_enabled=false 表示仅发送。返回配置结果；需要配置权限。

成功

local r = afn.create_channel({
  name="yard_gate",
  primary_frequency="station.gate.*.!test!staff",
  secondary_mode="none",
  value_present=true, value_kind="text", channel_value="READY",
  displayed=true
})
assert(r.success, r.error)

失败

local r = afn.create_channel({
  name="broken", value_present=true
})
print(r.success, r.error) -- 缺少 channel_value，整次拒绝

只修改给出的字段，失败不会部分提交。同一表中不得混用相互冲突的新旧别名；value_present=false 表示清除值，不能同时提供 channel_value。

成功

local r = afn.update_channel("yard_gate", {
  name="yard_exit",
  primary_frequency="station.exit.[1-4]",
  secondary_mode="auth"
})
assert(r.success, r.error)

清除值

assert(afn.update_channel("yard_exit", {
  value_present=false
}).success)

成功结果的 channel=nil；同步清租约、无线 actor 与 Synaxis endpoint。需要配置权限。

成功

local r = afn.remove_channel("temporary_config")
assert(r.success and r.channel == nil)

失败

local r = afn.remove_channel("missing")
print(r.error) -- unknown_channel

兼容期只为旧程序保留，无法表达同一信道同时拥有主频和值。新代码应组合使用 set_primary_frequency、set_value 和 clear_value。

旧代码仍可运行

local r = afn.set_channel_type("old_text", "frequency", "factory.line.*")
assert(r.success, r.error)

失败

local r = afn.set_channel_type("old_text", "frequency")
print(r.error) -- frequency_required_for_type_change

兼容期只为旧程序保留。新代码直接用类型明确的 Lua 值调用 set_value；旧 coordinate/player 仍可读取但不可新建。

旧代码仍可运行

local r = afn.set_information_subtype("counter", "real", 42.5)
assert(r.success, r.error)

失败

local r = afn.set_information_subtype("counter", "boolean", "yes")
print(r.error) -- invalid_information_value

配置权限format 为 real 或 boolean。Real 的值小于 1 表示关闭，达到 1 后转换并限制到 1～15；Boolean 的 false/true 对应 0/15。x/y 必须同时提供，省略格式时保留当前格式。

assert(afn.set_synaxis_activation(
  "door", true, "real", 12, 20
).success)
assert(afn.set_synaxis_activation("door", false).success)

明确给出 format 时可选 real/vec3/quaternion/boolean；省略或传空字符串保留值输入当前格式。x/y 必须同时提供。该端口只改值，不激活，也不修改另外两个端口。

Quaternion 值输入与安全关闭

assert(afn.set_synaxis_receive(
  "vehicle_rotation", true, "quaternion", 20, 70
).success)
-- 省略 format 关闭并保留接收格式；发布方向不受影响
assert(afn.set_synaxis_receive("vehicle_rotation", false).success)

失败

local r = afn.set_synaxis_receive("notice", true, "boolean")
print(r.error) -- invalid_synaxis_port

格式与坐标规则同值输入，但独立配置。比如 4 项实数组发布为 vec3 时只取前三项；Quaternion 缺少的 w 补 1。不存在或无法转换的值输出 Schema 安全默认值。该端口不激活信道。

Quaternion 值输出与安全关闭

assert(afn.set_synaxis_publish(
  "vehicle_rotation", true, "quaternion", 88, 70
).success)
assert(afn.set_synaxis_publish("vehicle_rotation", false).success)

失败

local r = afn.set_synaxis_publish("vehicle_rotation", true, "quaternion", 200, 70)
print(r.error) -- invalid_synaxis_position

side 以桥接器大屏幕正面为基准，为 front/back/left/right/up/down 或字符串 "all"（左右是玩家正对屏幕时看到的左右）；strength 为精确整数 1～15 或字符串 "all"（任意非零输入）。支持具体方向/全向与具体强度/全强度的四种组合；匹配时采用实际输入强度。数字不是阈值。一个信道最多保存 112 个不同组合且不会重复保存完全相同项；GUI 新增行默认双 all。返回配置结果；需要配置权限。

四种组合

assert(afn.bind_redstone("yard_gate", "front", 15).success)
assert(afn.bind_redstone("site_alarm", "all", "all").success)
assert(afn.bind_redstone("precision_alarm", "all", 7).success)
assert(afn.bind_redstone("left_input", "left", "all").success)
-- 依次表示：精确组合、双通配、全向精确强度、具体方向全强度

失败

local r = afn.bind_redstone("yard_gate", "north", 15)
print(r.error) -- invalid_redstone_binding

传具体方向只移除该方向的行；传 "all" 只移除全向行，不会连带删除六个具体方向。返回配置结果；需要配置权限。

成功

assert(afn.unbind_redstone("yard_gate", "front").success)
assert(afn.unbind_redstone("site_alarm", "all").success)

失败

local r = afn.unbind_redstone("missing", "front")
print(r.error) -- invalid_redstone_binding

frequency 必须合法非空；strength 1～15，默认 15；auth 默认 false。返回动作字段和唯一 handle。需要激活权限。

成功

local r = afn.transmit_temporary("factory.*.!test!maintenance", 12, false)
assert(r.success, r.error)
print(r.handle)

失败

local r = afn.transmit_temporary("secure.gate", 15, true)
print(r.error) -- auth_board_unavailable

ticks 1～1200，默认 20。返回 handle；到期关闭并产生 timeout 事件。

成功

local r = afn.pulse_temporary("station.bell", 15, 40, false)
assert(r.success, r.error)

失败

local ok, err = pcall(afn.pulse_temporary, "station.bell", 15, 0)
if not ok then printError(err) end

不能清其他电脑的 handle；ComputerID 仍获准时不要求激活权限。安装鉴权板后移出白名单会自动关闭该电脑全部 handle。返回动作结果。

成功

local tx = afn.transmit_temporary("factory.test")
assert(tx.success)
assert(afn.clear_temporary(tx.handle).success)

失败

local r = afn.clear_temporary("unknown")
print(r.error) -- unknown_temporary_handle

返回：removed_count integer。其他电脑和持久信道不受影响；ComputerID 仍获准时不要求激活权限，安装鉴权板后撤销白名单时同一清理会自动执行。

成功

afn.transmit_temporary("test.one")
afn.transmit_temporary("test.two")
print(afn.clear_temporary_all()) -- 2

失败

local ok, err = pcall(afn.clear_temporary_all, "missing")
if not ok then printError(err) end