factorio_api/
lib.rs

1//! Generated Factorio runtime API bindings.
2//!
3//! These types exist for Rust type-checking and IDE support. Mod code is
4//! transpiled to Lua and never executes these stub implementations.
5
6#![allow(
7    dead_code,
8    unused_imports,
9    unused_variables,
10    non_upper_case_globals,
11    clippy::all,
12    clippy::pedantic,
13    clippy::nursery
14)]
15
16/// Marker trait for autogenerated Factorio API types.
17/// Do not implement this trait manually.
18pub trait LuaObject {}
19
20/// Opaque placeholder for complex Factorio Lua API values.
21#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
22pub struct LuaAny;
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
25pub struct LuaStorage;
26
27impl LuaStorage {
28    #[must_use]
29    pub const fn new() -> Self {
30        Self
31    }
32
33    /// Read a value from Factorio's mod-local `storage` table.
34    ///
35    /// Lowers to `storage[key]`. Missing keys are Lua `nil` -> [`None`].
36    /// Prefer this over indexing when you want a typed optional read.
37    ///
38    /// ```ignore
39    /// storage.set("counter", 0_u32);
40    /// let n = storage.get::<u32>("counter").unwrap_or(0);
41    /// ```
42    #[allow(unused_variables)]
43    pub fn get<T>(&self, key: &str) -> Option<T> {
44        None
45    }
46
47    /// Persist a value in Factorio's mod-local `storage` table.
48    ///
49    /// Lowers to `storage[key] = value`. Prefer this over Rust `static` /
50    /// `LazyLock` (unsupported) for state that must survive events and save/load.
51    ///
52    /// Read values back with [`Self::get`] (typed [`Option`]) or indexing
53    /// (`storage["key"]` -> opaque [`LuaAny`]).
54    #[allow(unused_variables)]
55    pub fn set<V>(&self, key: &str, value: V) {}
56}
57
58impl From<LuaStorage> for LuaAny {
59    fn from(_: LuaStorage) -> Self {
60        LuaAny
61    }
62}
63
64impl std::ops::Index<&str> for LuaStorage {
65    type Output = LuaAny;
66
67    fn index(&self, _key: &str) -> &LuaAny {
68        &LUA_ANY
69    }
70}
71
72const LUA_ANY: LuaAny = LuaAny;
73
74#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
75pub struct Serpent;
76
77impl Serpent {
78    #[must_use]
79    pub const fn new() -> Self {
80        Self
81    }
82
83    /// Multi-line pretty-print (`serpent.block`).
84    #[allow(unused_variables)]
85    pub fn block(&self, value: impl Into<LuaAny>) -> &'static str {
86        ""
87    }
88
89    /// Single-line pretty-print (`serpent.line`).
90    #[allow(unused_variables)]
91    pub fn line(&self, value: impl Into<LuaAny>) -> &'static str {
92        ""
93    }
94
95    /// Serialize to a string that `serpent.load` can revive (`serpent.dump`).
96    #[allow(unused_variables)]
97    pub fn dump(&self, value: impl Into<LuaAny>) -> &'static str {
98        ""
99    }
100}
101
102#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
103pub struct LuaFunction;
104
105impl LuaFunction {
106    #[must_use]
107    pub const fn new() -> Self {
108        Self
109    }
110
111    /// Call this Lua function with no arguments. Lowers to `self()`.
112    #[must_use]
113    pub fn invoke0<R>(&self) -> R {
114        loop {}
115    }
116
117    /// Call this Lua function with one argument. Lowers to `self(arg)`.
118    #[allow(unused_variables)]
119    pub fn invoke<A>(&self, _arg: A) {}
120}
121
122impl From<LuaFunction> for LuaAny {
123    fn from(_: LuaFunction) -> Self {
124        LuaAny
125    }
126}
127
128/// Factorio [`LocalisedString`](https://lua-api.factorio.com/latest/concepts/LocalisedString.html):
129/// a plain string or a translation table `{ "category.key", arg1, ... }`.
130///
131/// Pass a string, or an array of strings (locale key plus `__1__` / `__2__` args).
132/// `.into()` is transparent when lowering, so `[key, name].into()` becomes
133/// `{ key, name }` in Lua.
134#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
135pub struct LocalisedString;
136
137impl From<LocalisedString> for LuaAny {
138    fn from(_: LocalisedString) -> Self {
139        LuaAny
140    }
141}
142
143impl<'a> From<&'a str> for LocalisedString {
144    fn from(_: &'a str) -> Self {
145        Self
146    }
147}
148
149impl From<String> for LocalisedString {
150    fn from(_: String) -> Self {
151        Self
152    }
153}
154
155impl<'a, const N: usize> From<[&'a str; N]> for LocalisedString {
156    fn from(_: [&'a str; N]) -> Self {
157        Self
158    }
159}
160
161impl<R> From<fn() -> R> for LuaFunction {
162    fn from(_: fn() -> R) -> Self {
163        LuaFunction
164    }
165}
166
167impl<A, R> From<fn(A) -> R> for LuaFunction {
168    fn from(_: fn(A) -> R) -> Self {
169        LuaFunction
170    }
171}
172
173impl<A, B, R> From<fn(A, B) -> R> for LuaFunction {
174    fn from(_: fn(A, B) -> R) -> Self {
175        LuaFunction
176    }
177}
178
179impl<A, B, C, R> From<fn(A, B, C) -> R> for LuaFunction {
180    fn from(_: fn(A, B, C) -> R) -> Self {
181        LuaFunction
182    }
183}
184
185impl<A, B, C, D, R> From<fn(A, B, C, D) -> R> for LuaFunction {
186    fn from(_: fn(A, B, C, D) -> R) -> Self {
187        LuaFunction
188    }
189}
190
191/// Coerce a Rust `fn` item or closure to [`LuaFunction`].
192///
193/// Prefer this for closures (`lua_fn(|e| { ... })`). Fn items also implement
194/// [`From`] for [`LuaFunction`] directly for common arities.
195#[must_use]
196pub fn lua_fn<F, A, R>(_f: F) -> LuaFunction
197where
198    F: Fn(A) -> R,
199{
200    LuaFunction
201}
202
203#[must_use]
204pub fn lua_fn0<F, R>(_f: F) -> LuaFunction
205where
206    F: Fn() -> R,
207{
208    LuaFunction
209}
210
211#[must_use]
212pub fn lua_fn2<F, A, B, R>(_f: F) -> LuaFunction
213where
214    F: Fn(A, B) -> R,
215{
216    LuaFunction
217}
218
219pub trait IntoOptionalLuaFunction {
220    fn into_optional_lua_function(self) -> Option<LuaFunction>;
221}
222
223impl IntoOptionalLuaFunction for LuaFunction {
224    fn into_optional_lua_function(self) -> Option<LuaFunction> {
225        Some(self)
226    }
227}
228
229impl IntoOptionalLuaFunction for Option<LuaFunction> {
230    fn into_optional_lua_function(self) -> Option<LuaFunction> {
231        self
232    }
233}
234
235impl<R> IntoOptionalLuaFunction for fn() -> R {
236    fn into_optional_lua_function(self) -> Option<LuaFunction> {
237        Some(self.into())
238    }
239}
240
241impl<A, R> IntoOptionalLuaFunction for fn(A) -> R {
242    fn into_optional_lua_function(self) -> Option<LuaFunction> {
243        Some(self.into())
244    }
245}
246
247impl<A, B, R> IntoOptionalLuaFunction for fn(A, B) -> R {
248    fn into_optional_lua_function(self) -> Option<LuaFunction> {
249        Some(self.into())
250    }
251}
252
253impl<A, B, C, R> IntoOptionalLuaFunction for fn(A, B, C) -> R {
254    fn into_optional_lua_function(self) -> Option<LuaFunction> {
255        Some(self.into())
256    }
257}
258
259impl<A, B, C, D, R> IntoOptionalLuaFunction for fn(A, B, C, D) -> R {
260    fn into_optional_lua_function(self) -> Option<LuaFunction> {
261        Some(self.into())
262    }
263}
264
265/// Index-or-name parameter used by APIs such as `game.get_player` /
266/// `game.get_surface` (`uint32 | string` in the Factorio schema).
267#[derive(Debug, Clone, Copy, PartialEq, Eq)]
268pub enum IndexOrName {
269    Index(u32),
270    Name(&'static str),
271}
272
273impl Default for IndexOrName {
274    fn default() -> Self {
275        Self::Index(0)
276    }
277}
278
279impl From<u32> for IndexOrName {
280    fn from(value: u32) -> Self {
281        Self::Index(value)
282    }
283}
284
285impl From<&'static str> for IndexOrName {
286    fn from(value: &'static str) -> Self {
287        Self::Name(value)
288    }
289}
290
291impl From<IndexOrName> for LuaAny {
292    fn from(_: IndexOrName) -> Self {
293        LuaAny
294    }
295}
296
297// Primitive types usable as LuaAny positions via `.into()`.
298impl<'a> From<&'a str> for LuaAny {
299    fn from(_: &'a str) -> Self {
300        LuaAny
301    }
302}
303impl From<String> for LuaAny {
304    fn from(_: String) -> Self {
305        LuaAny
306    }
307}
308impl From<bool> for LuaAny {
309    fn from(_: bool) -> Self {
310        LuaAny
311    }
312}
313impl From<u8> for LuaAny {
314    fn from(_: u8) -> Self {
315        LuaAny
316    }
317}
318impl From<u16> for LuaAny {
319    fn from(_: u16) -> Self {
320        LuaAny
321    }
322}
323impl From<u32> for LuaAny {
324    fn from(_: u32) -> Self {
325        LuaAny
326    }
327}
328impl From<u64> for LuaAny {
329    fn from(_: u64) -> Self {
330        LuaAny
331    }
332}
333impl From<i8> for LuaAny {
334    fn from(_: i8) -> Self {
335        LuaAny
336    }
337}
338impl From<i16> for LuaAny {
339    fn from(_: i16) -> Self {
340        LuaAny
341    }
342}
343impl From<i32> for LuaAny {
344    fn from(_: i32) -> Self {
345        LuaAny
346    }
347}
348impl From<i64> for LuaAny {
349    fn from(_: i64) -> Self {
350        LuaAny
351    }
352}
353impl From<f32> for LuaAny {
354    fn from(_: f32) -> Self {
355        LuaAny
356    }
357}
358impl From<f64> for LuaAny {
359    fn from(_: f64) -> Self {
360        LuaAny
361    }
362}
363impl From<usize> for LuaAny {
364    fn from(_: usize) -> Self {
365        LuaAny
366    }
367}
368
369// Concept types usable as LuaAny positions.
370impl From<crate::concepts::MapPosition> for LuaAny {
371    fn from(_: crate::concepts::MapPosition) -> Self {
372        LuaAny
373    }
374}
375impl From<crate::concepts::BoundingBox> for LuaAny {
376    fn from(_: crate::concepts::BoundingBox) -> Self {
377        LuaAny
378    }
379}
380impl From<crate::concepts::Color> for LuaAny {
381    fn from(_: crate::concepts::Color) -> Self {
382        LuaAny
383    }
384}
385
386impl std::ops::Index<&str> for LuaAny {
387    type Output = crate::settings::ModSettingValue;
388    fn index(&self, _key: &str) -> &Self::Output {
389        &crate::settings::UNIT_MOD_SETTING
390    }
391}
392
393/// Common "virtual fields" on `LuaAny` values.
394impl LuaAny {
395    pub fn x(self) -> f64 {
396        0.0
397    }
398    pub fn y(self) -> f64 {
399        0.0
400    }
401    pub fn left_top(self) -> LuaAny {
402        LuaAny
403    }
404    pub fn right_bottom(self) -> LuaAny {
405        LuaAny
406    }
407    pub fn value(self) -> LuaAny {
408        LuaAny
409    }
410}
411
412/// Marker trait for types that can be used as Factorio mod setting values.
413pub trait SettingValue: Copy + 'static {
414    const STUB: Self;
415}
416
417impl SettingValue for bool {
418    const STUB: Self = false;
419}
420impl SettingValue for u8 {
421    const STUB: Self = 0;
422}
423impl SettingValue for u16 {
424    const STUB: Self = 0;
425}
426impl SettingValue for u32 {
427    const STUB: Self = 0;
428}
429impl SettingValue for u64 {
430    const STUB: Self = 0;
431}
432impl SettingValue for usize {
433    const STUB: Self = 0;
434}
435impl SettingValue for i8 {
436    const STUB: Self = 0;
437}
438impl SettingValue for i16 {
439    const STUB: Self = 0;
440}
441impl SettingValue for i32 {
442    const STUB: Self = 0;
443}
444impl SettingValue for i64 {
445    const STUB: Self = 0;
446}
447impl SettingValue for f32 {
448    const STUB: Self = 0.0;
449}
450impl SettingValue for f64 {
451    const STUB: Self = 0.0;
452}
453impl SettingValue for &'static str {
454    const STUB: Self = "";
455}
456
457impl LuaAny {
458    /// Read a typed mod setting value by name.
459    ///
460    /// # Example
461    /// ```ignore
462    /// const CASUAL_MODE: bool = settings.startup.get::<bool>("ms-casual-mode");
463    /// const SPAWN_RADIUS: i64 = settings.startup.get::<i64>("ms-spawn-radius");
464    /// ```
465    pub const fn get<T: SettingValue>(&self, _key: &str) -> T {
466        T::STUB
467    }
468}
469
470include!(concat!(env!("OUT_DIR"), "/mod.rs"));
471
472/// Stub for [`std::ops::Index`] on [`classes::LuaGuiElement`] (children by name).
473const LUA_GUI_ELEMENT: classes::LuaGuiElement = classes::LuaGuiElement;
474
475impl std::ops::Index<&str> for classes::LuaGuiElement {
476    type Output = classes::LuaGuiElement;
477
478    /// Index children by name (`frame["child"]`). Missing children are Factorio
479    /// `nil` at runtime; rustc still sees a stub handle (same honesty as
480    /// [`LuaStorage`] indexing).
481    fn index(&self, _name: &str) -> &classes::LuaGuiElement {
482        &LUA_GUI_ELEMENT
483    }
484}
485
486pub mod lua_libs;
487pub mod prototypes;
488pub mod settings;
489
490pub use event_filters::{
491    EventFilterEntry, FilterMethodSpec, PrototypeFilterEntry, filter_method_spec,
492};
493pub use lua_libs::{LuaMath, LuaStringLib, LuaTableLib};
494pub use map::{event_filter_type, event_type_to_name};
495pub use unions::literal_enum_variant_str;
496
497/// Re-export generated flag-set helper (dict-of-true concepts).
498pub use concepts::is_flag_set_type;
499
500pub mod prelude {
501    pub use crate::LocalisedString;
502    pub use crate::SettingValue;
503    pub use crate::concepts::*;
504    pub use crate::event_data::*;
505    pub use crate::event_filters::*;
506    pub use crate::event_type_to_name;
507    pub use crate::events::*;
508    pub use crate::globals::*;
509    pub use crate::lua_fn;
510    pub use crate::lua_fn0;
511    pub use crate::lua_fn2;
512    pub use crate::prototypes;
513    pub use crate::prototypes::{
514        AssemblingMachine, BoundingBox, Color, EnergySource, Fluid, Item, MinableProperties,
515        Recipe, RecipeIngredient, RecipeProduct, Technology, TechnologyUnit,
516        TechnologyUnitIngredient, UnlockRecipeEffect,
517    };
518    pub use crate::settings::{
519        BoolSetting, DoubleSetting, IntSetting, ModSettingValue, SettingsDictionary, StringSetting,
520        data, settings,
521    };
522    pub use crate::unions::*;
523}
factorio_api/lib.rs

factorio_api/
lib.rs
