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

factorio_api/
lib.rs
