Official Factorio Wiki - User contributions [en]

Types/AnimationFrameSequence

2023-02-05T10:23:37Z

Stringweasel: Spelling mistake "comple"

An [[Types/table|array]] of [[Types/uint16]]. Used by [[Types/Animation]] and similar.

This is a list of 1-based frame indices into the spritesheet. The actual length of the animation will then be the length of the frame_sequence (times <code>repeat_count</code>, times two if <code>run_mode</code> is "forward-then-backward"). There is a limit for (actual) animation length of 255 frames.

Indices can be used in any order, repeated or not used at all. Unused frames are not loaded into VRAM at all, frames referenced multiple times are loaded just once.[https://forums.factorio.com/53202]

== Examples ==

Trivial example - frame_sequence defines same sequence in which the animation would load by default, so it is useless in this case:
<syntaxhighlight lang="lua">
frame_count = 4,
frame_sequence = { 1, 2, 3, 4 }
</syntaxhighlight>

Usage example - first five times repeat frame 2, then alternate between 4 and 3 two times. Frame 1 is not used:
<syntaxhighlight lang="lua">
frame_count = 4,
frame_sequence = { 2, 2, 2, 2, 2, 4, 3, 4, 3 }
</syntaxhighlight>

Complex example - animation contains different layers with different frame counts
<syntaxhighlight lang="lua">
local custom_frame_sequence = { 2, 2, 2, 2, 2, 4, 3, 4, 3 }
layers = {
{
-- Animation with custom frame sequence
frame_count = 4,
frame_sequence = custom_frame_sequence,
},
{
-- Single sprite that's repeated
repeat_count = #custom_frame_sequence,
},
{
-- Other animation with different frame count
-- Assuming: #custom_frame_sequence < frame_count
frame_count = #custom_frame_sequence,
},
}
</syntaxhighlight>

Types/UnitSpawnDefinition

2022-11-08T20:44:04Z

Stringweasel: Add information about spawn points

The definition of a spawnable unit for a [[Prototype/EnemySpawner]]. It can be specified as a table with named or numbered keys, but not a mix of both.

== Mandatory properties ==

=== unit or 1 ===
'''Type''': [[Types/string]]

The name of a [[Prototype/Entity]].

=== spawn_points or 2 ===
'''Type''': [[Types/table]] of [[Types/SpawnPoint]]

Array of evolution and probability info.
* The evolution_factor must be ascending from entry to entry.
* The last entry's weight will be used when the evolution_factor is larger than the last entry.
* Weights are linearly interpolated between entries.
* Individual weights are scaled linearly so that the cumulative weight is 1.

Types/AnimationFrameSequence

2022-10-29T07:35:15Z

Stringweasel: show advanced example using multiple layers

An [[Types/table|array]] of [[Types/uint16]]. Used by [[Types/Animation]] and similar.

This is a list of 1-based frame indices into the spritesheet. The actual length of the animation will then be the length of the frame_sequence (times <code>repeat_count</code>, times two if <code>run_mode</code> is "forward-then-backward"). There is a limit for (actual) animation length of 255 frames.

Indices can be used in any order, repeated or not used at all. Unused frames are not loaded into VRAM at all, frames referenced multiple times are loaded just once.[https://forums.factorio.com/53202]

== Examples ==

Trivial example - frame_sequence defines same sequence in which the animation would load by default, so it is useless in this case:
<syntaxhighlight lang="lua">
frame_count = 4,
frame_sequence = { 1, 2, 3, 4 }
</syntaxhighlight>

Usage example - first five times repeat frame 2, then alternate between 4 and 3 two times. Frame 1 is not used:
<syntaxhighlight lang="lua">
frame_count = 4,
frame_sequence = { 2, 2, 2, 2, 2, 4, 3, 4, 3 }
</syntaxhighlight>

Comple example - animation contains different layers with different frame counts
<syntaxhighlight lang="lua">
local custom_frame_sequence = { 2, 2, 2, 2, 2, 4, 3, 4, 3 }
layers = {
{
-- Animation with custom frame sequence
frame_count = 4,
frame_sequence = custom_frame_sequence,
},
{
-- Single sprite that's repeated
repeat_count = #custom_frame_sequence,
},
{
-- Other animation with different frame count
-- Assuming: #custom_frame_sequence < frame_count
frame_count = #custom_frame_sequence,
},
}
</syntaxhighlight>

Types/Animation

2022-10-28T18:00:03Z

Stringweasel: animation_speed only has to be defined in one layer

== Basics ==
Specifies animation that can be used in the game.

Note that if any frame of the animation is specified from the same source as any other [[Types/Sprite]] or frame of other animation, it will be shared.

== Optional properties ==

=== layers ===
'''Type''': [[Types/table]] of [[Types/Animation]]

If this property is present, all Animation definitions have to be placed as entries in the array, and they will all be loaded from there. Each item (Animation definition) in the array may also have the <code>layers</code> property.

If this property is present, all other properties are ignored and the mandatory properties do not have to be defined.

Layers may not be an empty table.

=== hr_version ===
'''Type''': [[Types/Animation]]

If this property exists and high resolution sprites are turned on, its contents are used to load the Animation.

=== filename ===
'''Type''': [[Types/FileName]]

'''Default''': ""

Mandatory if <code>"stripes"</code> is not specified.

=== priority ===
'''Type''': [[Types/SpritePriority]]

'''Default''': "medium"

=== flags ===
'''Type''': [[Types/SpriteFlags]]

=== size ===
'''Type''': [[Types/SpriteSizeType]] or [[Types/table]] of [[Types/SpriteSizeType]]

The width and height of the one frame. If this is an array, the first member of the array is the width and the second is the height. Otherwise the size is both width and height.

Width and height may only be in the range of 0-8192.

=== width ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>size</code> is not given. Width of one frame in pixels, from 0-8192.

=== height ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>size</code> is not given. Height of one frame in pixels, from 0-8192.

=== x ===
'''Type''': [[Types/SpriteSizeType]]

'''Default''': 0

Horizontal position of the animation in the source file in pixels.

=== y ===
'''Type''': [[Types/SpriteSizeType]]

'''Default''': 0

Vertical position of the animation in the source file in pixels.

=== position ===
'''Type''': [[Types/table]] of [[Types/SpriteSizeType]]

Loaded only when <code>x</code> and <code>y</code> are both 0. The first member of the array is x and the second is y.

=== shift ===
'''Type''': [[Types/vector]]

'''Default''': {0, 0}

=== scale ===
'''Type''': [[Types/double]]

'''Default''': 1

Values different than 1 specify the scale of the animation on default zoom.
Scale 2 means that the picture will be 2 times bigger on screen (and more pixelated).

=== draw_as_shadow ===
'''Type''': [[Types/bool]]

'''Default''': false

Only one of <code>draw_as_shadow</code>, <code>draw_as_glow</code> and <code>draw_as_light</code> can be true. <code>draw_as_shadow</code> takes precedence over <code>draw_as_glow</code> and <code>draw_as_light</code>.

=== draw_as_glow ===
'''Type''': [[Types/bool]]

'''Default''': false

Only one of <code>draw_as_shadow</code>, <code>draw_as_glow</code> and <code>draw_as_light</code> can be true. <code>draw_as_glow</code> takes precedence over <code>draw_as_light</code>.

Draws first as a normal sprite, and again as a light layer.[https://forums.factorio.com/91682]

=== draw_as_light ===
'''Type''': [[Types/bool]]

'''Default''': false

Only one of <code>draw_as_shadow</code>, <code>draw_as_glow</code> and <code>draw_as_light</code> can be true.

=== mipmap_count ===
'''Type''': [[Types/uint8]]

'''Default''': 0

Only loaded if this is an icon (has flag "group=icon" or "group=gui"). 
Note: mipmap_count doesn't make sense in animation, as it is not possible to layout mipmaps in a way, that would load correctly both the animation and the mipmaps (besides animations with just one frame).[https://forums.factorio.com/viewtopic.php?p=549058#p549058]

=== apply_runtime_tint ===
'''Type''': [[Types/bool]]

'''Default''': false

=== tint ===
'''Type''': [[Types/Color]]

'''Default''': {r=1, g=1, b=1, a=1} (white)

=== blend_mode ===
'''Type''': [[Types/BlendMode]]

'''Default''': "normal"

=== load_in_minimal_mode ===
'''Type''': [[Types/bool]]

'''Default''': false

Minimal mode is entered when mod loading fails. You are in it when you see the gray box after (part of) the loading screen that tells you a mod error ([https://cdn.discordapp.com/attachments/340530709712076801/532315796626472972/unknown.png Example]). If you are a modder, you can just ignore this property.

=== premul_alpha ===
'''Type''': [[Types/bool]]

'''Default''': true

Whether alpha should be premultiplied.

=== generate_sdf ===
'''Type''': [[Types/bool]]

'''Default''': false

Unused.

=== run_mode ===
'''Type''': [[Types/string]]

'''Default''': "forward"

Possible values are:
*forward
*backward
*forward-then-backward

=== frame_count ===
'''Type''': [[Types/uint32]]

'''Default''': 1

Can't be 0.

=== line_length ===
'''Type''': [[Types/uint32]]

'''Default''': 0

Once the specified number of pictures is loaded, other pictures are loaded on other line.
This is to allow having longer animations in matrix, to input files with too high width.
The game engine limits the width of any input files to 8192px, so it is compatible with most graphics cards.
0 means that all the pictures are in one horizontal line.

=== animation_speed ===
'''Type''': [[Types/float]]

'''Default''': 1

Modifier of the animation playing speed, the default is 1, which means one animation frame per tick (60 fps).
The speed of playing can often vary depending on the usage (output of steam engine for example). Has to be greater than 0.
If <code>layers</code> are used then the <code>animation_speed</code> only has to be defined in one layer. All layers will run at the same speed.

=== max_advance ===
'''Type''': [[Types/float]]

'''Default''': MAX_FLOAT

=== repeat_count ===
'''Type''': [[Types/uint8]]

'''Default''': 1

How many times to repeat the animation to complete an animation cycle. E.g. if one layer is 10 frames, a second layer of 1 frame would need repeat_count = 10 to match the complete cycle.

Can't be 0.

=== dice ===
'''Type''': [[Types/uint8]]

=== dice_x ===
'''Type''': [[Types/uint8]]

=== dice_y ===
'''Type''': [[Types/uint8]]

=== frame_sequence ===
'''Type''': [[Types/AnimationFrameSequence]]

=== stripes ===
'''Type''': [[Types/table|table]] (array) of [[Types/Stripe|Stripe]]

== Example ==
Specification of animation of a beacon
<syntaxhighlight lang="lua">
animation =
{
filename = "__base__/graphics/entity/beacon/beacon-antenna.png",
width = 54,
height = 50,
line_length = 8,
frame_count = 32,
shift = { -0.03125, -1.71875},
animation_speed = 0.5
},</syntaxhighlight>

{{Prototype property type usage|{{FULLPAGENAME}}?Animation]}}

Scenario system

2022-10-22T09:05:08Z

Stringweasel: Scenarios need a info.json to be used to host a new multiplayer game.

{{Languages}}
The scenario system allows save-based mods to be created, so that installing mods separately is not necessary. This allows for server side scripting, or to provide a separate objective than the vanilla freeplay (which is actually a scenario, just like the [[tutorial|tutorial campaign]]).

== Creation ==

Creation of a scenario starts in the [[map editor]]. The map editor allows an author to save a map that they have created as a scenario. This allows players to add special scripting to the scenario.

There are two ways to create a scenario:

* Via the [[Map editor]].
* Creating a new folder in the scenarios folder, and adding a control.lua.

== Differences between scenarios, saves, and mods ==

There are a few differences between a scenario, a save, and a mod. In a way, a scenario takes parts from both.

* Scenarios, unlike mods, cannot add anything to the game. The only type of scripting allowed in a scenario is scripting that would occur in control.lua.
* Scenarios can have premade maps, such as the supply scenario, or can have maps made with the map generator, such as freeplay.
* Scenarios do not need to be installed client side, unlike mods. This allows servers to implement small changes to gameplay on their end, such as displaying a MOTD to joining players.
* Scenarios, unlike normal saves, are stored in a different folder.
* Scenarios can be used to create a bit of a story, as the campaign does.

== Limitations of Scenarios ==

* Scenarios must be packaged into a mod to be distributed on the mod portal.
* Scenarios cannot add anything to the game (Namely, they may not make calls to data:extend()).
* Scenarios count as mods for the purpose of isolating [[achievements]].
* Scenarios can be packaged without an <code>info.json</code> and <code>description.json</code>, but then it won't be possible to host a new multiplayer game using this scenario.

== Playing a scenario ==

There are several scenarios included into the game by default. To play a scenario, click Play->Scenarios, and choose either a user scenario, or a scenario from the base game or mod. The Freeplay scenario is the same as the basic game, where the objective is to launch a rocket.

Upon choosing a scenario to play and saving the game, a normal save will be created that encompasses the map itself, and the control.Lua scripting that was provided by the scenario. This can be removed by deleting the script.dat and control.Lua files from the save, turning it into a normal save. Do this at your own risk, as it may break the save depending on how intertwined the scenario is with the save.

== Installing scenarios ==

Scenarios made by other players can be installed into a folder called scenarios in the player's [[application directory#User_data_directory|user data directory]]. It can then be played from the scenarios menu.

Scenarios added by mods are also shown in the Scenarios menu.

== Packaging a scenario as a mod ==
Create an empty mod, as described in [[Tutorial:Mod_structure]]. Then, simply add a "scenarios" folder, and copy your scenario into that folder. If you created a scenario with the map editor, you can find it in the scenarios folder in your [[application directory#User_data_directory|user data directory]].

== See also ==

* [[Tutorial]]
* [[Map editor]]
* [[Map generator]]

Types/SimulationDefinition

2022-10-19T14:18:39Z

Stringweasel: expand game.move_cursor with comment

Used by [[Prototype/TipsAndTricksItem]] and by main menu simulations ([[Prototype/UtilityConstants#main_menu_simulations]]).

== Optional properties ==

=== save ===
'''Type''': [[Types/FileName]]

The save file that is used for this simulation. If not given and <code>generate_map</code> is true, a map gets generated by the game.

=== init_file ===
'''Type''': [[Types/FileName]]

This code is run as a (silent) console command inside the simulation when it is first initialized. Since this is run as a console command, the restrictions of console commands apply, e.g. <code>require</code> is not available[https://lua-api.factorio.com/latest/Libraries.html].

=== init ===
'''Type''': [[Types/string]]

'''Default''': ""

Only loaded if <code>init_file</code> is not present.

This code is run as a (silent) console command inside the simulation when it is first initialized. Since this is run as a console command, the restrictions of console commands apply, e.g. <code>require</code> is not available[https://lua-api.factorio.com/latest/Libraries.html].

=== update_file ===
'''Type''': [[Types/FileName]]

This code is run as a (silent) console command inside the simulation every time the simulation is updated. Since this is run as a console command, the restrictions of console commands apply, e.g. <code>require</code> is not available[https://lua-api.factorio.com/latest/Libraries.html].

=== update ===
'''Type''': [[Types/string]]

'''Default''': ""

Only loaded if <code>update_file</code> is not present.

This code is run as a (silent) console command inside the simulation every time the simulation is updated. Since this is run as a console command, the restrictions of console commands apply, e.g. <code>require</code> is not available[https://lua-api.factorio.com/latest/Libraries.html].

=== init_update_count ===
'''Type''': [[Types/uint32]]

'''Default''': 0

Amount of ticks that this simulation should run for before the simulation is shown to the player. These updates happen after init/init_file has been run and at the highest possible rate (> 60 UPS).

=== length ===
'''Type''': [[Types/uint32]]

'''Default''': 0

How long this simulation takes. In the main menu simulations, another simulation will start after this simulation ends.

=== generate_map ===
'''Type''': [[Types/bool]]

'''Default''': false

If <code>save</code> is not given and this is true, a map gets generated by the game for use in the simulation.

=== checkboard ===
'''Type''': [[Types/bool]]

'''Default''': true

If this is true, the map of the simulation is set to be a lab-tile checkerboard in the area of {{-20, -15},{20, 15}} when the scenario is first initialized (before init/init_file run).

=== volume_modifier ===
'''Type''': [[Types/float]]

Multiplier for the simulation volume set by the player in the sound settings.

=== override_volume ===
'''Type''': [[Types/bool]]

If true, overrides the simulation volume set by the player in the sound settings, simply setting the volume modifier to 1.

== Addition API ==

Simulation-only APIs:
<syntaxhighlight lang="lua">
game.create_test_player{name=string}
game.activate_rail_planner{position=position,ghost_mode=bool}
game.deactivate_rail_planner()
game.move_cursor{position=position,speed=number} --[[should be called every tick. Returns true when target is reached]]
game.activate_selection()
game.finish_selection()
game.deactivate_selection()
game.scroll_clipboard_forwards()
game.scroll_clipboard_backwards()
game.camera_player_cursor_position [RW]
game.camera_position [RW]
game.camera_zoom [W]
game.camera_player [W]
game.camera_player_cursor_direction [W]
game.camera_alt_info [W]
game.smart_belt_building [W]

player.drag_start_position [W]
player.raw_build_from_cursor{ghost_mode=bool,created_by_moving=bool,position=position}

surface.create_entities_from_blueprint_string{string=string,position=position,force=force,direction=defines.direction,flip_horizonal=bool,flip_vertical=bool,by_player=player}
</syntaxhighlight>

Types/IconSpecification

2022-10-17T07:14:30Z

Stringweasel: Add note about limitations in layered icon definitions.

== Basics ==
Specifies the icon of an entity/item/technology/recipe etc. The properties are specified directly in the prototype, not in another sub-property.

Either <code>icons</code> and optionally <code>icon_size</code>, or both <code>icon</code> and <code>icon_size</code> have to be specified. If both <code>icons</code> and <code>icon</code> are defined, <code>icon</code> is ignored.
== Prototype properties: Option 1 ==
=== icons ===
'''Type''': [[Types/table]] of [[Types/IconData]]

The rendering order of the individual icons follows the table (array) order: Later added icons (higher index) get drawn on top of previously added icons (lower index). Can't be an empty table.

'''Note:''' Icon layering was mainly designed for the barrel recipes and might not handle all modded instances correctly. Depending on the use-case it might be benifitial to use non-layered icons. For reference see [https://forums.factorio.com/69221 here] and [https://forums.factorio.com/98732 here].

=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory if <code>icon_size</code> is not specified inside all instances of [[Types/IconData]] inside <code>icons</code>. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

'''Default''': 0

== Prototype properties: Option 2 ==
=== icon ===
'''Type''': [[Types/FileName]]

Path to the icon file.
=== icon_size ===
'''Type''': [[Types/SpriteSizeType]]

Mandatory. The size of the square icon, in pixels, e.g. 32 for a 32px by 32px icon.

=== icon_mipmaps ===
'''Type''': [[Types/uint8]]

Icons of reduced size will be used at decreased scale. 0 or 1 mipmaps is a single image. The file must contain 1/2 size images with a geometric-ratio, for each mipmap level. Each next level is aligned to the upper-left corner. Example sequence: 128x128@(0,0), 64,64@(128,0), 32x32@(196,0) is 3 mipmaps.

'''Default''': 0

== Examples ==

Simple icon with size:
<syntaxhighlight lang="lua">
icon = "__base__/graphics/icons/fluid/heavy-oil.png",
icon_size = 32,
</syntaxhighlight>

Layered icon, size defined outside of layers:
<syntaxhighlight lang="lua">icon_size = 32,
icons = {
{
icon = "__base__/graphics/icons/fluid/barreling/empty-barrel.png"
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-side-mask.png",
tint = { a = 0.75, b = 0, g = 0, r = 0 }
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-hoop-top-mask.png",
tint = { a = 0.75, b = 0.5, g = 0.5, r = 0.5 }
}
}</syntaxhighlight>

Layered icon, size defined per layer:
<syntaxhighlight lang="lua">icons = {
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty.png",
icon_size = 32
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty-side-mask.png",
icon_size = 32,
tint = { a = 0.75, b = 0, g = 0, r = 0 }
},
{
icon = "__base__/graphics/icons/fluid/barreling/barrel-empty-top-mask.png",
icon_size = 32,
tint = { a = 0.75, b = 0.5, g = 0.5, r = 0.5 }
},
{
icon = "__base__/graphics/icons/fluid/crude-oil.png",
icon_size = 32,
scale = 0.5,
shift = {7, 8 }
}
}</syntaxhighlight>