factoriax.playground.editor.state

factoriax.playground.editor.state#

The level under edit, as mutable numpy arrays.

The editor holds a level in plain numpy arrays, so an edit needs no JAX. The editor converts to or from Level at three moments only: it loads a file, it saves a file, or it starts a play session.

Every field of EditorState has the name and the shape of the level field that it holds. A conversion therefore copies, and does not translate.

Module Attributes

`NUM_INVENTORY_SLOTS`	Number of inventory rows that the editor shows for one player.
`InvTarget`	Target of an inventory operation.

class factoriax.playground.editor.state.EditorState(name: str, map_width: int, map_height: int, block_map: ndarray, block_resources: ndarray, machine_types: ndarray, machine_directions: ndarray, machine_inventory: ndarray, player_inventory: list[tuple[int, int]] | None=None, player_inventories: dict[int, list[tuple[int, int]]]=<factory>, player_positions: dict[int, tuple[int, int]]=<factory>, dirty: bool = False)#

The level that the editor has open.

Every field has the name and the shape of the field of Level that it holds. The arrays are numpy and not JAX, and the functions of this module write to them in place.

machine_inventory records the contents of a machine by item, as the level does, and records no slot. When the engine builds the state, it gives each item a slot. It selects that slot from the part that the item has in the recipe of that machine. A slot order in this class can therefore not survive a save, and does not agree with the engine.

name#

Identifier of the level. A save writes it to the file.

Type:: str

map_width, map_height: Tile dimensions. Every array field has these dimensions.

block_map#

BlockType of each tile. Shape (map_height, map_width).

Type:: numpy.ndarray

block_resources#

Ore units in each tile. A zero means an empty deposit, and not “use the default”.

Type:: numpy.ndarray

machine_types#

Machine on each tile, and NONE where the tile is clear.

Type:: numpy.ndarray

machine_directions#

Facing of each tile. The value has no meaning on a tile with no machine.

Type:: numpy.ndarray

machine_inventory#

Contents of the machine on each tile, by item. Shape (map_height, map_width, NUM_ITEM_TYPES).

Type:: numpy.ndarray

player_inventory#

(item, count) pairs that every player starts with, or None.

Type:: list[tuple[int, int]] | None

player_inventories#

Contents for one player, with the player index as the key. For a player that it names, it replaces player_inventory.

Type:: dict[int, list[tuple[int, int]]]

player_positions#

(x, y) spawn tile of each player, with the player index as the key. A save numbers the players by list position, so a gap in these keys closes on the way out.

Type:: dict[int, tuple[int, int]]

dirty#

True after an edit that no save has written yet.

Type:: bool

factoriax.playground.editor.state.InvTarget#

Target of an inventory operation. It is ("player", player_index, 0) for a player, or ("machine", tile_x, tile_y) for a machine.

alias of tuple[str, int, int]

factoriax.playground.editor.state.NUM_INVENTORY_SLOTS: int = 10#: Number of inventory rows that the editor shows for one player. The engine holds a player inventory by item and has no slot, so this number is a display width and not a limit of the engine.

class factoriax.playground.editor.state.ResourceBrush(mode: str = 'exact', exact_value: int = 30000, range_min: int = 1, range_max: int = 30000)#

Amount of ore that the editor writes to each tile that it paints.

mode#

"exact" gives every tile the same amount. "range" gives each tile its own random amount.

Type:: str

exact_value#

Amount for one tile in "exact" mode.

Type:: int

range_min, range_max: Lowest and highest amount in "range" mode. Both ends are included.

factoriax.playground.editor.state.add_column(state: EditorState) → None#

Add one column of dirt tiles to the right edge of the map.

The function makes every array one column wider, and adds 1 to map_width.

Parameters:: state – Editor state. The function writes to it.

factoriax.playground.editor.state.add_row(state: EditorState) → None#

Add one row of dirt tiles to the bottom edge of the map.

The function makes every array one row taller, and adds 1 to map_height.

Parameters:: state – Editor state. The function writes to it.

factoriax.playground.editor.state.clear_inventory_slot(state: EditorState, target: tuple[str, int, int], slot: int) → None#

Clear one slot.

Parameters:

state – Editor state. The function writes to it.
target – Player or machine to write to.
slot – Index of the row.

factoriax.playground.editor.state.editor_state_from_level(level: Level) → EditorState#

Return an editor state that holds the contents of a level.

A level field that holds None gives the editor the value that the engine applies by default. For block_resources this is a full deposit on each ore tile, and for the other fields it is an empty array.

Every array and every list is a copy, so an edit in the editor cannot reach the level that this function read.

Parameters:: level – Level to read. The function does not modify it.
Returns:: The same level, in the form that the editor writes to.
Return type:: EditorState

factoriax.playground.editor.state.editor_state_to_level(state: EditorState) → Level#

Return a level that holds the contents of the editor state.

An optional field becomes None when it holds what the engine applies by default. This keeps the saved file small, and the value that comes back is the same.

block_resources is the one field where a zero and None are different instructions. None tells the engine to fill each ore tile, and a zero tells it that the deposit is empty. The function therefore compares against the default, and does not test for zeros.

Parameters:: state – Editor state to read. The function does not modify it.
Returns:: A level that a save or build_state() can read.
Return type:: Level

factoriax.playground.editor.state.erase_block(state: EditorState, x: int, y: int) → None#

Set one tile to dirt, and keep the machine on that tile.

The ore of the tile becomes zero. A column or a row outside the map has no effect.

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.erase_entity(state: EditorState, x: int, y: int) → None#

Remove each entity at one tile.

A player is the only entity that the editor puts on a tile, so this function calls remove_player_at().

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.erase_machine(state: EditorState, x: int, y: int) → None#

Remove the machine from one tile, and keep the block of that tile.

The contents of the machine are lost. A column or a row outside the map has no effect.

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.erase_tile(state: EditorState, x: int, y: int) → None#

Set one tile to dirt, and remove the machine on that tile.

This function calls erase_block() and then erase_machine().

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.fill_rect_tiles(state: EditorState, x0: int, y0: int, x1: int, y1: int, block: int, brush: ResourceBrush, rng: Generator) → None#

Paint a rectangle of tiles with a block type.

The rectangle includes all four edges. If an edge is outside the map, the function moves that edge to the map. A rectangle fully outside the map has no effect.

In "range" mode each tile of an ore rectangle gets its own random amount.

Parameters:

state – Editor state. The function writes to it.
x0 – Column and row of one corner.
y0 – Column and row of one corner.
x1 – Column and row of the opposite corner.
y1 – Column and row of the opposite corner.
block – BlockType value to write.
brush – Brush that gives the ore amount.
rng – Random generator that the brush reads in "range" mode.

factoriax.playground.editor.state.get_inventory_slots(state: EditorState, target: tuple[str, int, int]) → list[tuple[int, int]]#

Return the contents of a player or a machine, as one row for each slot.

For a machine the rows are a view over machine_inventory. The machine records its contents by item, so each item fills one row, and the rows follow the item order. An item can therefore not hold two rows.

The list holds at least NUM_INVENTORY_SLOTS rows for a player, and at least MAX_MACHINE_INVENTORY_SLOTS rows for a machine. A machine with more items than that gets one row for each item, so no item is lost.

Parameters:

state – Editor state to read.
target – Player or machine to read.

Returns:

One (item, count) pair for each row. An empty row is (ItemType.EMPTY, 0).

Return type:

list[tuple[int, int]]

factoriax.playground.editor.state.get_num_slots(state: EditorState, target: tuple[str, int, int]) → int#

Return the number of slots that a player or a machine has.

Parameters:

state – Editor state to read.
target – Player or machine to read.

Returns:

NUM_INVENTORY_SLOTS for a player. For a machine, the slot count of that machine type.

Return type:

int

factoriax.playground.editor.state.new_editor_state(width: int, height: int, name: str = 'untitled') → EditorState#

Return a new editor state of dirt tiles.

Parameters:

width – Map width in tiles.
height – Map height in tiles.
name – Identifier of the level.

Returns:

A level of dirt tiles, with no ore, no machine, and no player.

Return type:

EditorState

factoriax.playground.editor.state.remove_column(state: EditorState) → None#

Remove the right column of the map.

A player on that column is removed with it. A map one tile wide does not change.

Parameters:: state – Editor state. The function writes to it.

factoriax.playground.editor.state.remove_player_at(state: EditorState, x: int, y: int) → None#

Remove each player that has its spawn tile at one tile.

This can leave a gap in the player numbering. editor_state_to_level() closes that gap.

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.remove_row(state: EditorState) → None#

Remove the bottom row of the map.

A player on that row is removed with it. A map one tile tall does not change.

Parameters:: state – Editor state. The function writes to it.

factoriax.playground.editor.state.sample_resource(brush: ResourceBrush, rng: Generator) → int#

Return the ore amount for one tile.

Parameters:

brush – Brush that gives the mode and the limits.
rng – Random generator. The function reads it in "range" mode only.

Returns:

Ore amount for one tile.

Return type:

int

factoriax.playground.editor.state.set_inventory_slot(state: EditorState, target: tuple[str, int, int], slot: int, item_type: int, count: int) → None#

Put one item and its count in one slot.

For a machine the slot is a row of the view that get_inventory_slots() returns. The write removes the item that the row showed. If the same item is already in another row, the machine keeps one entry for that item, and this count replaces the earlier one.

A count of 0, or an item of ItemType.EMPTY, clears the row.

Parameters:

state – Editor state. The function writes to it.
target – Player or machine to write to.
slot – Index of the row.
item_type – ItemType value to write.
count – Number of items.

factoriax.playground.editor.state.set_machine(state: EditorState, x: int, y: int, machine: int, direction: int) → None#

Put a machine on one tile, and clear the contents of that tile.

A machine that was on the tile is lost, together with its contents. A column or a row outside the map has no effect.

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.
machine – Machine value to write.
direction – Direction value for the facing.

factoriax.playground.editor.state.set_player_position(state: EditorState, player_idx: int, x: int, y: int) → None#

Set the spawn tile of one player.

If the player has a spawn tile, the function moves that player to the new tile. A column or a row outside the map has no effect.

Parameters:

state – Editor state. The function writes to it.
player_idx – Index of the player.
x – Tile column.
y – Tile row.

factoriax.playground.editor.state.set_tile(state: EditorState, x: int, y: int, block: int, brush: ResourceBrush, rng: Generator) → None#

Paint one tile with a block type, and set the ore of that tile.

An ore block gets its amount from the brush. Every other block gets zero. A column or a row outside the map has no effect.

Parameters:

state – Editor state. The function writes to it.
x – Tile column.
y – Tile row.
block – BlockType value to write.
brush – Brush that gives the ore amount.
rng – Random generator that the brush reads in "range" mode.