Mod changes in 0.12

[Rseding91]

As you may have read (or may not - I can't read minds yet) - most mods will break in 0.12 due to API name changes.

For those wanting to attempt to update your mods before 0.12 hits this is the 0.12 mod related change log as of July 4 2015:

Mod related changes

• Changed all the identifiers/methods/events/parameters. Underscores are used as word delimiter (findentities -> find_entities).
• Changed glob to global.
• New object LuaSurface, accessible from player/entity as read property surface.
• Some commands moved from LuaGame to LuaSurface: get_pollution, can_place_entity, find_entity, find_entities, find_entities_filtered, find_non_colliding_position, find_enemy_units, find_nearest_enemy, set_multi_command, create_entity, create_unit_group, build_enemy_base, get_tile, get_tileproperties, set_tiles, pollute, get_chunks, is_chunk_generated
• Added LuaFluidPrototype - similar to LuaItemPrototype but for fluids.
• math.random can now accept negative values for ranges eg x + math.random(-10, 10)
• Added LuaRecipe::hidden and energy read.
• New object LuaGroup, accessible from LuaEntityPrototype as read property group/subgroup. LuaGroup contains: name, type, inventory_order, group, subgroups
• Added several new options to LuaEntityPrototype: mineable_properties, items_to_place_this, collision_box, selection_box, order, group, subgroup, healing_per_tick, emissions_per_tick, corpses, selectable_in_game, weight, resistances, fast_replaceable_group, loot, repair_speed_modifier
• LuaItemPrototype::group now returns the new LuaGroup object.
• Added LuaEntity::is_crafting() - returns true/false if the assembling machine or furnace is currently crafting a recipe.
• Added LuaEntity::crafting_progress/bonus_progress - a percent of 1: the current crafting progress or bonus progress.
• Added the ability to compare LuaObjects using "==" as in: "if game.player == game.players[1]" for all LuaObjects.
• Removed all LuaObject::equals(): the == operator can be used in its place.
• Added new blend modes for sprites using "blend_mode" property. Possible values: "normal", "additive", "multiplicative".
• Added on_player_driving_changed_state event - passes the player_index who's driving state changed.
• Added LuaEntity::belt_to_ground_type - returns the type "input"/"output" of the transport-belt-to-ground.
• Added several methods for manipulating gates: is_opened, is_opening, is_closed, is_closing, request_to_open, request_to_close.
• Changed LuaEntity::neighbours: For electric poles: the wire connections: {copper={}, red={}, green={}}. For transport-belt-to-ground: the input/output entity it's connected to (or none). For entities with fluid - the entities the fluid connections connect to indexed by the fluid connection.
• #entity.fluidbox can now be read from any entity and will return the number of fluidboxes the entity has (0 for non-fluid handling entities).
• Added the ability to specify map colors for all entities: map_color, friendly_map_color, and enemy_map_color
• Added the ability to disable drawing the station name for train-stop type entities: chart_name = "false" in the prototype.
• LuaEntity::backer_name can now be read/written for all entities that support backer names (furnace, assembling machine, lab, locomotive, radar, roboport, trainstop).
• LuaEntity::recipe can now be set to nil to remove the recipe from an assembling machine.
• Added LuaItemPrototype default_request_amount, resistances, item_to_clear.
• Added LuaChart::chart_all (charts all the generated parts of the map).
• Expanded LuaEntity::get_item_count and LuaEntity::clear to work with all transport belt entities.
• New object LuaTransportLine, accessible from entity as read method get_transport_line(index) - an interface to the items on transport belts.
• Added LuaSurface::count_entities_filtered - the same as find_entities_filtered but simply returns a count. The benefits being: it's much faster than find_entities_filtered when the entity references aren't desired.
• Added LuaForce::enable_research() - enables research for the force if it was disabled.
• Added LuaSurface::spill_item_stack() - takes a item_stack and position and drops the items on the ground item bomb style.
• Changed LuaEntity::stack, LuaEntity::held_stack and LuaPlayer::cursor_stack to return LuaItemStack objects.
• Changed LuaItemStack to allow reading any inventory slot even when the item in the slot is invalid. LuaItemStack::valid_for_read should be used before accessing the normal properties/methods for a given LuaItemStack.
• Removed LuaEntity::clear_circuit_condition() - LuaEntity::set_circuit_condition(index, nil) can be used instead.
• Added "force" option to LuaSurface::find_entities_filtered/count_entities_filtered.
• ItemStack counts can be excluded and defaults to 1, ItemStacks can be strings and default to a full stack.
• Added LuaItemStack::count write support.
• Added LuaItemStack::can_set_stack(), set_stack(), clear() - write support to a specific item stack.
• Removed LuaEntity::stack, held_stack write support - LuaItemStack::set_stack() can be used.
• Removed LuaPlayer::cursor_stack write support - LuaItemStack::set_stack() can be used.
• Added LuaTrain::cargo_wagons read - returns only the cargo wagons for the given train.
• Added LuaEntity::remove_market_item - takes an index to remove from a Market entity offer list.
• Added LuaEntity::get_market_items - returns a table of offers the Market entity offers.
• Added LuaForce::research_progress read/write - a percent of 1 - the current research progress (0 if no research).
• Added LuaEntityPrototype::turret_range read - the range of a given turret entity prototype.
• Added player_index to the on_put_item event.
• Added ghosts from manual building and blueprints to the on_built_entity event.
• Added LuaPlayer::enable_flashlight() - counterpart to disable_flashlight().
• Replaced LuaGameScript::kill_all_enemies() by LuaForce::kill_all_units().
• Changed on_researched events to return the related LuaTechnology object.
• Added LuaTechnology::force read - the LuaForce the technology belongs to.
• Added LuaGame::create_surface - takes a string name and optionally a table of map gen settings and creates a new surface.
• Changed LuaPlayer::teleport to allow optionally a surface name, index or object to teleport the player to. The surface must exist.
• Added LuaSurface::request_to_generate_chunks - takes a position and radius and requests to generate those chunks - will not generate chunks outside the map bounds.
• Added LuaSurface::map_gen_settings - the current map gen settings for the surface.

It's by no means 100% final and we may have missed a thing or two but that should cover a majority of the changes required. If anyone has questions about a specific change feel free to post and I'll do my best to explain them (since I wrote most of the changes).

We'll be updating the wiki after 0.12 has been released with the new information but as the wiki is now it contains none of the 0.12 mod changes.

EDIT: this python script:

renamer.zip

(2.61 KiB) Downloaded 532 times

can be used to cover the majority of the renames required "findentities" -> "find_entities".

[YuokiTani]

- Turrets change to 2x2 tiles ... will graphics without player overlay work ? (if this overlay-animation-sheet missing)
- and will this player-color-overlay-sheets possible work on all graphics like assemblys or walls ?
- will it possible to change player-animation-directions- and framecount (sheet) without crashing the game ?
- will some entity/items - methods such as energy_source, horizontal_animation, filename, width, production etc. renamed or restructed ?

questions over questions ... as always modders are alone and need reverse engineering to find out whats changed by trying their mods and looking at endless not useful error-messages.
but hey thats is modding fun ... or maybe not.

i hope i'am the only one with this impression and other modders have a better experience ...

[Rseding91]

- Turrets change to 2x2 tiles ... will graphics without player overlay work ? (if this overlay-animation-sheet missing)
- and will this player-color-overlay-sheets possible work on all graphics like assemblys or walls ?
- will it possible to change player-animation-directions- and framecount (sheet) without crashing the game ?
- will some entity/items - methods such as energy_source, horizontal_animation, filename, width, production etc. renamed or restructed ?

questions over questions ... as always modders are alone and need reverse engineering to find out whats changed by trying their mods and looking at endless not useful error-messages.
but hey thats is modding fun ... or maybe not.

i hope i'am the only one with this impression and other modders have a better experience ...

I'm a mod creator myself so I'm well aware of the frustration updating mods to work between versions. I've actually updated your mod, tree farm, part of dytech and all of mine to work in 0.12 so I could test my save file as I made API changes. I have a plan to make the error messages far more helpful and not like they are now "Expected node 'width'" - 100% useless error message you can get now.

#1: I'm not sure I understand the question?
#2: the player color overlay is only applied to a few specific entities right now (turrets, gates, tanks, cars, players) - things that are specific to players. Stuff like assembling machines have no concept of an owner so it wouldn't make sense to have them use the players color that placed them.
#3: Sort of, it has to be a specific count - if it's not the specific count it gives an error message on startup stating how many directions are required and forces the count to be that.
#4: We made a script that (should) contain all of the simple name changes - I'll edit the post and include it.

[ljdp]

Added the ability to compare LuaObjects using "==" as in: "if game.player == game.players[1]" for all LuaObjects.
Removed all LuaObject::equals(): the == operator can be used in its place.

Does this mean LuaObjects can be properly used as keys?

Code: Select all

local entity = some_LuaEntity
local tbl = {}
tbl[entity] = true
if tbl[entity] then
   print("true")
end

[Rseding91]

Added the ability to compare LuaObjects using "==" as in: "if game.player == game.players[1]" for all LuaObjects.
Removed all LuaObject::equals(): the == operator can be used in its place.

Does this mean LuaObjects can be properly used as keys?

Code: Select all

local entity = some_LuaEntity
local tbl = {}
tbl[entity] = true
if tbl[entity] then
   print("true")
end

LuaObjects can already be used as keys. The issue comes from save/load stability in that using a LuaObject (a Lua table) as a key uses the address of the table which is random from when the Lua state is created and won't be the same address of the LuaObject when you save, exit, and load the game.

[ljdp]

I hadn't thought of that. What would be useful then is a unique ID for each entity. I've added an interface request.

[YuokiTani]

- Turrets change to 2x2 tiles ... will graphics without player overlay work ? (if this overlay-animation-sheet missing)
#1: I'm not sure I understand the question?
#2: the player color overlay is only applied to a few specific entities right now (turrets, gates, tanks, cars, players) - things that are specific to players. Stuff like assembling machines have no concept of an owner so it wouldn't make sense to have them use the players color that placed them.
#3: Sort of, it has to be a specific count - if it's not the specific count it gives an error message on startup stating how many directions are required and forces the count to be that.

1) is the player-overlay optional or a needed graphic in next version ?
2) sure in friendly Co-Op Multiplayer not, but in a Player vs. Player Scenario - and if is not planed it's good until it appears in a future version
3) the game crashs after using the graphic and switching gfx in play ... looks like some hardcoded values and lua-code ignored/passed the code-check ... but i aim for changeing the gfx ... make the lua-values useless in this case.

[orzelek]

Could we get some explanation whats behind the LuaSurface objects?

It's stated in the changes that it will be a read property of player or entity. This leaves me with question how to get LuaSurface for arbitrary location to spawn ores in RSO. Entity creation function will be now in the surface so I need to get that surface from somewhere thats position not entity related.

There is also a note in RSO thread about absolute coordinates going away - is that tied to LuaSurfaces and what consequence it will have on spawning ore? Especially if the spawning can happen on currently generated chunk and it's neighbors?

[Oxyd]

A surface is like a dimension. Surfaces aren't on locations; it's the other way around: Locations are on surfaces.

If you want to iterate through all surfaces, you can simply do

Code: Select all

for _, s in pairs(game.surfaces) do 
  whatever_you_want(s); 
end

Or you can simply limit yourself to only doing things to the default surface, game.surfaces['nauvis']. That will be the only surface in the game anyway unless a player (through the console) or a mod creates a new surface.

The read-only properties of player and entity simply give you the surface the player or entity is currently located on.

[Rseding91]

To expand on what Oxyd said:

The event "on_chunk_generated" will pass "surface" - the surface of the chunk generated
Player has property "surface" - the surface the player is on
Entity has a property "surface" - the surface the entity is on (all events that pass entity can use this)
game.surfaces can be iterated to get all surfaces
game.get_surface can be used to get a specific surface by index or name (names can't be changed once a surface is created) - the default surface name is provided by Oxyd above

In all other events that pass player or entity information the player/entity "surface" property can be used.

[orzelek]

Thanks for the explanation - seems that safest way to go is to use event provided surface. Later might need to make sure I'm not generating ore on surface that represents the space platform I guess.

[GotLag]

game.alwaysday=true no longer works in console, is there a new way to do this or has it been disabled?

[orzelek]

game.alwaysday=true no longer works in console, is there a new way to do this or has it been disabled?

Try game.always_day=true - global change to add separator.

[GotLag]

Cheers, it works. Hadn't thought to try that.

A more serious problem: the changes to belt mechanics have completely broken my lane splitters. I was spawning invisible decoration entities to block half of each output belt, but the new belts seem to ignore collisions entirely.

[ratchetfreak]

Cheers, it works. Hadn't thought to try that.

A more serious problem: the changes to belt mechanics have completely broken my lane splitters. I was spawning invisible decoration entities to block half of each output belt, but the new belts seem to ignore collisions entirely.

isn't that kinda the point of the new belt system.

can you rearrange the "rails" of the belts instead?

[GotLag]

Oh no doubt it's more efficient the new way. It's just that the old way let me tinker with belt outputs without having to add any real event handling (other than placement and removal of the modified splitters).

[yeganer]

I may be wrongt but it seems that LuaTrain.locomotives is broken. At least i'm failing to access locomotives.frontmovers and locomotives.backmovers

[orzelek]

I may be wrongt but it seems that LuaTrain.locomotives is broken. At least i'm failing to access locomotives.frontmovers and locomotives.backmovers

You need underscores - front_movers and back_movers will work most likely.

[Choumiko]

• Added on_player_driving_changed_state event - passes the player_index who's driving state changed.

So, my quick test revealed that this event triggers whenever a player enters or leaves a vehicle right? Would it be possible to pass the entity that was entered/left too? For entered it's not that important as it's just player.vehicle, when leaving it's not that clean.
Also, the same thing for opening/closing a GUI/inventory of an entity would be awesome.

[Ty94]

New object LuaTransportLine, accessible from entity as read method get_transport_line(index) - an interface to the items on transport belts.

Can someone explain what methods and properties the LuaTransportLine object has. Because when I run get_transport_line, all I get is an empty table.