factorio-codegen 0.2.0

[!NOTE] This project is in development; expect breaking changes.

factorio-rs is a Rust authoring layer for Factorio mods. You write a Factorio-oriented subset of Rust; the CLI typechecks against generated API stubs, applies transpile-time safety lints, and emits a normal Factorio mod (Lua + info.json + locale/assets). The game still loads Lua, this is not native code inside Factorio.

Why

Typed Factorio APIs - cargo check / rust-analyzer against generated stubs (runtime classes plus ~260 data-stage prototype stubs)
Transpile safety - lints catch Rust patterns that nil-crash or miscompile in Lua
Familiar Rust subset - structs, enums, collections, and same-crate traits / dyn dispatch - plus prototype macros (item!, recipe!, ...)
Cargo-shaped deps - share APIs between mods with #[factorio_rs::export] and normal Cargo dependencies
Familiar workflow - init / check / build / package / install / test

	Lua mods	factorio-rs
Runs as Factorio Lua	✅	✅
Typed Factorio API stubs	❌	✅
rust-analyzer / `cargo check`	❌	✅
Transpile-time safety lints	❌	✅
CLI packaging (`info.json`, stages)	❌	✅
Typed cross-mod exports via Cargo	❌	✅
Full Lua language surface	✅	❌
Rust syntax (supported subset)	❌	✅

Quick start

Requires Rust 1.88+ (edition 2024; let-chains in if / while).

cargo install factorio-rs-cli
mkdir my-mod && cd my-mod
factorio-rs init --name my-mod
factorio-rs build

dist/ is a loadable Factorio mod. Use factorio-rs install / open when you have a Factorio install; use factorio-rs test to run in-game #[test]s.

Pipeline

Typecheck with cargo check (API stubs + Cargo deps)
Discover stage modules (control, settings, data, ...)
Lower Rust -> IR and apply transpile lints
Optionally prune unreachable code
Emit Lua under output_dir (default dist/)

Docs

Book: https://languint.github.io/factorio-rs/
Start: Getting started - First hour
Recipes / language: Testing - Dependencies - Supported Rust - Lints
crates.io: factorio-rs - factorio-rs-cli
Changelog: CHANGELOG.md
Contributing: CONTRIBUTING.md
Discord: https://discord.gg/Tq8243rqmn

Preview the docs site locally:

cd docs
pnpm install
pnpm dev

Examples

Example	What it shows
`hello_world`	Minimal control-stage event
`gui_basics`	Framed GUI + `LuaStyle`
`locale_test`	`locale!` and mod settings
`provider` / `consumer`	Cross-mod exports via Cargo
`tracing_test`	Optional `tracing` -> `game.print`
`traits_demo`	Traits: static, defaults, `&dyn`
`mandatory_spaghetti`	Larger control-stage sample

License

MIT