[lex]

luacheck only knows the Factorio API listed in .luacheckrc, and that list predates Factorio 2.1. Its defines were missing 820 values, so luacheck flagged valid code as "accessing undefined field" (defines.build_check_type.manual_ghost, most of the 2.x events, input actions and prototype types), and still had 109 that 2.1 no longer has (defines.time, circuit_connector_id, circuit_condition_index, difficulty_settings, build_check_type.ghost_place...), so it let code using them through, though they're nil in game. The control stage globals (game, script, rendering, prototypes...) were from 1.1: they still had rendering's 80 pre-2.0 functions (rendering.destroy, get_*/set_*) and game.get_filtered_entity_prototypes, help, desync_players, styles..., and lacked 31 fields, among them prototypes.recipe, prototypes.mod_data, game.create_inventory and script.get_event_name.

Change

• .github/scripts/luacheck-api.ps1 (new): regenerates the parts of .luacheckrc that come from the runtime API that Factorio publishes for each version (https://lua-api.factorio.com/2.1.24/runtime-api.json): the control stage globals game, script, prototypes, rendering, helpers, settings, commands, remote and rcon with their methods and attributes, and every define. They sit between -- luacheck-api.ps1: begin/end <part> lines; the script rewrites those and the -- Current Factorio Version line and leaves the rest of the file alone.
• .luacheckrc: both parts generated from 2.1.24. luacheck now flags a field the API doesn't have, writing to a global object (game = nil) and writing a read-only attribute (game.tick = 0). Attributes holding an object or a table (game.forces, settings.global) stay writable, so game.forces.player.manual_mining_speed_modifier = 1 passes (luacheck can't make a field read only but its contents writable). As before, script.on_event, on_init, on_load, on_nth_tick, generate_event_name, set_event_filter and commands.add_command are left out, so RedMew code goes through Event and Command.add.
• docs/LUACHECK.md (new): what is generated, what is left out on purpose and why, and how to update it for a new Factorio version. AGENTS.md points to it.
• resources/difficulty_settings.lua: the only code the new defines flag. Its default and expensive_recipe presets used defines.difficulty_settings, which went in 2.0 with expensive recipes. default now holds 2.1's two difficulty settings, technology_price_multiplier and spoil_time_modifier, and expensive_recipe goes. Nothing requires the file (it's the example in redmew_surface.lua's comment), so no map changes.
• redmew_surface.lua's comment says what difficulty settings hold in 2.1.

Tests

• luacheck .: 0 warnings / 0 errors.
• On a scratch file, the new config flags rendering.destroy, game.write_file, game.get_filtered_entity_prototypes, game.tick = 0, helpers.stage = ..., script.on_event, script.generate_event_name, script.set_event_filter and commands.add_command, and passes prototypes.recipe[...], game.forces.player.x = 1, settings.global[...] = {...}, game.speed = 2 and defines.build_check_type.manual_ghost.
• The script's defines output is byte for byte the list the first commit made with a Python script, and running it again changes nothing.

Updating for a later Factorio version

pwsh .github/scripts/luacheck-api.ps1 2.1.24        # a version, downloaded from lua-api.factorio.com
pwsh .github/scripts/luacheck-api.ps1 runtime-api.json
luacheck .

What luacheck flags afterwards is code using API the new version removed or renamed.

🤖 Generated with Claude Code

[grilledham]

Optional suggestion: That python script you used. Maybe we should stick that in the docs folder with some explanation for how to use. Also convert it to pwsh to match what we use in the CI actions?

[RedRafe]

Need to update this Factorio version

[lex]

Done in 38128ae: it says 2.1.24 now, and luacheck-api.ps1 keeps it in step with the API it generates from.

[RedRafe]

This also needs updating

[lex]

Done in 38128ae. The whole control stage block (game, script, prototypes, rendering, helpers, settings, commands, remote, rcon) is now generated from the 2.1.24 runtime API, like defines. It drops the 80 pre-2.0 rendering functions and game.get_filtered_entity_prototypes, help, desync_players... and adds 31 that were missing (prototypes.recipe, prototypes.mod_data, game.create_inventory...). script.on_event/on_init/on_load/on_nth_tick/generate_event_name/set_event_filter and commands.add_command stay out on purpose, so code goes through Event and Command.add.

[lex]

Good idea, done in 38128ae: the script is now .github/scripts/luacheck-api.ps1, next to the other pwsh scripts, and it generates the control stage globals too. pwsh .github/scripts/luacheck-api.ps1 2.1.24 (or a downloaded runtime-api.json) rewrites only the marked parts of .luacheckrc. docs/LUACHECK.md explains how to use it and what it leaves out on purpose.