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
112impl From<LuaFunction> for LuaAny {
113    fn from(_: LuaFunction) -> Self {
114        LuaAny
115    }
116}
117
118/// Factorio [`LocalisedString`](https://lua-api.factorio.com/latest/concepts/LocalisedString.html):
119/// a plain string or a translation table `{ "category.key", arg1, ... }`.
120///
121/// Pass a string, or an array of strings (locale key plus `__1__` / `__2__` args).
122/// `.into()` is transparent when lowering, so `[key, name].into()` becomes
123/// `{ key, name }` in Lua.
124#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
125pub struct LocalisedString;
126
127impl From<LocalisedString> for LuaAny {
128    fn from(_: LocalisedString) -> Self {
129        LuaAny
130    }
131}
132
133impl<'a> From<&'a str> for LocalisedString {
134    fn from(_: &'a str) -> Self {
135        Self
136    }
137}
138
139impl From<String> for LocalisedString {
140    fn from(_: String) -> Self {
141        Self
142    }
143}
144
145impl<'a, const N: usize> From<[&'a str; N]> for LocalisedString {
146    fn from(_: [&'a str; N]) -> Self {
147        Self
148    }
149}
150
151impl<R> From<fn() -> R> for LuaFunction {
152    fn from(_: fn() -> R) -> Self {
153        LuaFunction
154    }
155}
156
157impl<A, R> From<fn(A) -> R> for LuaFunction {
158    fn from(_: fn(A) -> R) -> Self {
159        LuaFunction
160    }
161}
162
163impl<A, B, R> From<fn(A, B) -> R> for LuaFunction {
164    fn from(_: fn(A, B) -> R) -> Self {
165        LuaFunction
166    }
167}
168
169impl<A, B, C, R> From<fn(A, B, C) -> R> for LuaFunction {
170    fn from(_: fn(A, B, C) -> R) -> Self {
171        LuaFunction
172    }
173}
174
175impl<A, B, C, D, R> From<fn(A, B, C, D) -> R> for LuaFunction {
176    fn from(_: fn(A, B, C, D) -> R) -> Self {
177        LuaFunction
178    }
179}
180
181/// Coerce a Rust `fn` item or closure to [`LuaFunction`].
182///
183/// Prefer this for closures (`lua_fn(|e| { ... })`). Fn items also implement
184/// [`From`] for [`LuaFunction`] directly for common arities.
185#[must_use]
186pub fn lua_fn<F, A, R>(_f: F) -> LuaFunction
187where
188    F: Fn(A) -> R,
189{
190    LuaFunction
191}
192
193#[must_use]
194pub fn lua_fn0<F, R>(_f: F) -> LuaFunction
195where
196    F: Fn() -> R,
197{
198    LuaFunction
199}
200
201#[must_use]
202pub fn lua_fn2<F, A, B, R>(_f: F) -> LuaFunction
203where
204    F: Fn(A, B) -> R,
205{
206    LuaFunction
207}
208
209pub trait IntoOptionalLuaFunction {
210    fn into_optional_lua_function(self) -> Option<LuaFunction>;
211}
212
213impl IntoOptionalLuaFunction for LuaFunction {
214    fn into_optional_lua_function(self) -> Option<LuaFunction> {
215        Some(self)
216    }
217}
218
219impl IntoOptionalLuaFunction for Option<LuaFunction> {
220    fn into_optional_lua_function(self) -> Option<LuaFunction> {
221        self
222    }
223}
224
225impl<R> IntoOptionalLuaFunction for fn() -> R {
226    fn into_optional_lua_function(self) -> Option<LuaFunction> {
227        Some(self.into())
228    }
229}
230
231impl<A, R> IntoOptionalLuaFunction for fn(A) -> R {
232    fn into_optional_lua_function(self) -> Option<LuaFunction> {
233        Some(self.into())
234    }
235}
236
237impl<A, B, R> IntoOptionalLuaFunction for fn(A, B) -> R {
238    fn into_optional_lua_function(self) -> Option<LuaFunction> {
239        Some(self.into())
240    }
241}
242
243impl<A, B, C, R> IntoOptionalLuaFunction for fn(A, B, C) -> R {
244    fn into_optional_lua_function(self) -> Option<LuaFunction> {
245        Some(self.into())
246    }
247}
248
249impl<A, B, C, D, R> IntoOptionalLuaFunction for fn(A, B, C, D) -> R {
250    fn into_optional_lua_function(self) -> Option<LuaFunction> {
251        Some(self.into())
252    }
253}
254
255/// Index-or-name parameter used by APIs such as `game.get_player` /
256/// `game.get_surface` (`uint32 | string` in the Factorio schema).
257#[derive(Debug, Clone, Copy, PartialEq, Eq)]
258pub enum IndexOrName {
259    Index(u32),
260    Name(&'static str),
261}
262
263impl Default for IndexOrName {
264    fn default() -> Self {
265        Self::Index(0)
266    }
267}
268
269impl From<u32> for IndexOrName {
270    fn from(value: u32) -> Self {
271        Self::Index(value)
272    }
273}
274
275impl From<&'static str> for IndexOrName {
276    fn from(value: &'static str) -> Self {
277        Self::Name(value)
278    }
279}
280
281impl From<IndexOrName> for LuaAny {
282    fn from(_: IndexOrName) -> Self {
283        LuaAny
284    }
285}
286
287// Primitive types usable as LuaAny positions via `.into()`.
288impl<'a> From<&'a str> for LuaAny {
289    fn from(_: &'a str) -> Self {
290        LuaAny
291    }
292}
293impl From<String> for LuaAny {
294    fn from(_: String) -> Self {
295        LuaAny
296    }
297}
298impl From<bool> for LuaAny {
299    fn from(_: bool) -> Self {
300        LuaAny
301    }
302}
303impl From<u8> for LuaAny {
304    fn from(_: u8) -> Self {
305        LuaAny
306    }
307}
308impl From<u16> for LuaAny {
309    fn from(_: u16) -> Self {
310        LuaAny
311    }
312}
313impl From<u32> for LuaAny {
314    fn from(_: u32) -> Self {
315        LuaAny
316    }
317}
318impl From<u64> for LuaAny {
319    fn from(_: u64) -> Self {
320        LuaAny
321    }
322}
323impl From<i8> for LuaAny {
324    fn from(_: i8) -> Self {
325        LuaAny
326    }
327}
328impl From<i16> for LuaAny {
329    fn from(_: i16) -> Self {
330        LuaAny
331    }
332}
333impl From<i32> for LuaAny {
334    fn from(_: i32) -> Self {
335        LuaAny
336    }
337}
338impl From<i64> for LuaAny {
339    fn from(_: i64) -> Self {
340        LuaAny
341    }
342}
343impl From<f32> for LuaAny {
344    fn from(_: f32) -> Self {
345        LuaAny
346    }
347}
348impl From<f64> for LuaAny {
349    fn from(_: f64) -> Self {
350        LuaAny
351    }
352}
353impl From<usize> for LuaAny {
354    fn from(_: usize) -> Self {
355        LuaAny
356    }
357}
358
359// Concept types usable as LuaAny positions.
360impl From<crate::concepts::MapPosition> for LuaAny {
361    fn from(_: crate::concepts::MapPosition) -> Self {
362        LuaAny
363    }
364}
365impl From<crate::concepts::BoundingBox> for LuaAny {
366    fn from(_: crate::concepts::BoundingBox) -> Self {
367        LuaAny
368    }
369}
370impl From<crate::concepts::Color> for LuaAny {
371    fn from(_: crate::concepts::Color) -> Self {
372        LuaAny
373    }
374}
375
376impl std::ops::Index<&str> for LuaAny {
377    type Output = crate::settings::ModSettingValue;
378    fn index(&self, _key: &str) -> &Self::Output {
379        &crate::settings::UNIT_MOD_SETTING
380    }
381}
382
383/// Common "virtual fields" on `LuaAny` values.
384impl LuaAny {
385    pub fn x(self) -> f64 {
386        0.0
387    }
388    pub fn y(self) -> f64 {
389        0.0
390    }
391    pub fn left_top(self) -> LuaAny {
392        LuaAny
393    }
394    pub fn right_bottom(self) -> LuaAny {
395        LuaAny
396    }
397    pub fn value(self) -> LuaAny {
398        LuaAny
399    }
400}
401
402/// Marker trait for types that can be used as Factorio mod setting values.
403pub trait SettingValue: Copy + 'static {
404    const STUB: Self;
405}
406
407impl SettingValue for bool {
408    const STUB: Self = false;
409}
410impl SettingValue for u8 {
411    const STUB: Self = 0;
412}
413impl SettingValue for u16 {
414    const STUB: Self = 0;
415}
416impl SettingValue for u32 {
417    const STUB: Self = 0;
418}
419impl SettingValue for u64 {
420    const STUB: Self = 0;
421}
422impl SettingValue for usize {
423    const STUB: Self = 0;
424}
425impl SettingValue for i8 {
426    const STUB: Self = 0;
427}
428impl SettingValue for i16 {
429    const STUB: Self = 0;
430}
431impl SettingValue for i32 {
432    const STUB: Self = 0;
433}
434impl SettingValue for i64 {
435    const STUB: Self = 0;
436}
437impl SettingValue for f32 {
438    const STUB: Self = 0.0;
439}
440impl SettingValue for f64 {
441    const STUB: Self = 0.0;
442}
443impl SettingValue for &'static str {
444    const STUB: Self = "";
445}
446
447impl LuaAny {
448    /// Read a typed mod setting value by name.
449    ///
450    /// # Example
451    /// ```ignore
452    /// const CASUAL_MODE: bool = settings.startup.get::<bool>("ms-casual-mode");
453    /// const SPAWN_RADIUS: i64 = settings.startup.get::<i64>("ms-spawn-radius");
454    /// ```
455    pub const fn get<T: SettingValue>(&self, _key: &str) -> T {
456        T::STUB
457    }
458}
459
460include!(concat!(env!("OUT_DIR"), "/mod.rs"));
461
462pub mod lua_libs;
463pub mod prototypes;
464pub mod settings;
465
466pub use event_filters::{EventFilterEntry, FilterMethodSpec, filter_method_spec};
467pub use lua_libs::{LuaMath, LuaStringLib, LuaTableLib};
468pub use map::{event_filter_type, event_type_to_name};
469pub use unions::literal_enum_variant_str;
470
471pub mod prelude {
472    pub use crate::LocalisedString;
473    pub use crate::SettingValue;
474    pub use crate::concepts::*;
475    pub use crate::event_data::*;
476    pub use crate::event_filters::*;
477    pub use crate::event_type_to_name;
478    pub use crate::events::*;
479    pub use crate::globals::*;
480    pub use crate::lua_fn;
481    pub use crate::lua_fn0;
482    pub use crate::lua_fn2;
483    pub use crate::prototypes;
484    pub use crate::prototypes::{
485        AssemblingMachine, BoundingBox, Color, EnergySource, Fluid, Item, MinableProperties,
486        Recipe, RecipeIngredient, RecipeProduct, Technology, TechnologyUnit,
487        TechnologyUnitIngredient, UnlockRecipeEffect,
488    };
489    pub use crate::settings::{
490        BoolSetting, DoubleSetting, IntSetting, ModSettingValue, StringSetting, data, settings,
491    };
492    pub use crate::unions::*;
493}
factorio_api/lib.rs

factorio_api/
lib.rs
