Breaking mod API changes with version 0.17.35 (planned release on Thursday)

[Bilka]

With version 0.17.35 we are making a lot of changes that break mods. We want to give you the opportunity to prepare your mods for these changes, so we are already sharing the relevant parts of the changelog.

Breaking API changes
Modding (the data stage):

• Renamed the character entity type and name from "player" to "character" to make it consistent with how we call/access it in all other places.
• Renamed the technology personal-roboport-equipment-2 to personal-roboport-mk2-equipment and gave it corresponding icon to be consistent with other technologies of this kind.
• Renamed the technology power-armor-2 to power-armor-mk2 to be consistent with other technologies of this kind.

Scripting (the runtime scripts):

• Renamed defines.inventory.player_main, player_guns, player_ammo, player_armor, player_vehicle and player_trash to defines.inventory.character_main, character_guns, character_ammo, character_armor, character_vehicle and character_trash.
• Removed LuaStyle::title_top_padding, title_right_padding, title_bottom_padding and title_left_padding.

The player -> character rename only affects the prototypes. It's just a change of the prototype type and name. Nothing else. It does not mean that the runtime scripting function names are changing.

Other API changes
Modding (the data stage):

• Added optional storage tank prototype property "scale_info_icons".
• Added "manual_rail_building_reach_modifier" to the utility-constants.
• MapGenPresets' advanced_settings.difficulty_settings.research_queue_setting now works. (69546)

Scripting (the runtime scripts):

• Mod GUI root elements (top/left/center/goal) are now contained in scroll panes, so when there is not enough space, it will become scrollable instead of being cut off.
  With enough space, it looks the same as before, the only change is, that the mod GUI contents can now not expect to be squashed by the screen, as it will just make a scroll bar instead.
• Added LuaCircuitNetwork::connected_circuit_count read.
• Added LuaEntity::time_to_live read/write for highlight box entities.
• Added LuaEntity::allow_dispatching_robots read/write.
• Added LuaEntity::toggle_equipment_movement_bonus().
• Added LuaEquipmentGrid::inhibit_movement_bonus read/write.
• Added optional 'radius' to LuaSurface 'find_xyz' functions.
• Added defines.inventory.editor_main, editor_guns, editor_ammo, editor_armor.
• AutoplaceSpecification::control is always included in property tree, even for non-peak-based autoplace specifications. (69286)

[Earendel]

• Renamed the technology personal-roboport-equipment-2 to personal-roboport-mk2-equipment and gave it corresponding icon to be consistent with other technologies of this kind.

Personally I'd prefer it if all the equipment prototypes changed to follow the "personal-roboport-equipment-2" format to be consisted with other types of game prototypes and then the "MK" prefix can just be in the localisation (if it is needed at all).

[Bilka]

Some clarifications after discussion on discord:

Renamed the character entity type and name from "player" to "character" to make it consistent with how we call/access it in all other places.

This means that data.raw.player.player (the lil dude that you run around as) is now data.raw.character.character -> we changed the type and the name of it. Note that with the prototype rename, we also moved the graphics. The character icon is now character.png instead of player.png and the animations are now in the entity/character folder instead of entity/player. No, this does not change *anything* about the runtime API function names (the stuff documented on lua-api.factorio.com).

Renamed defines.inventory.player_main, player_guns, player_ammo, player_armor, player_vehicle and player_trash to defines.inventory.character_main, character_guns, character_ammo, character_armor, character_vehicle and character_trash.

These were already character specific, and would not work correctly for things like the god controller. Now the names reflect this. So, this is not a change in functionality. I would suggest to take the opportunity of this change to change any usage of get_inventory(defines.inventory.player_main) or get_inventory(defines.inventory.god_main) to get_main_inventory(). It's shorter and it always works correctly!

[mrudat]

So, a bold search and destroy would look something like the following:

Code: Select all

s/get_inventory\(\s*defines.inventory.(?:player|god)_main\s*)/get_main_inventory()/g;
s/defines.inventory.player/defines.inventory.character/g;
s/power-armor-2/power-armor-mk2/g;
s/personal-roboport-equipment-2/personal-roboport-mk2-equipment/g;

The player -> character rename in the data phase is non-trivial to do with a simple search-and-replace, as there are so many different ways to reference data.raw.player.player.

[Amarula]

Thank you!

[bobingabout]

• Renamed the technology personal-roboport-equipment-2 to personal-roboport-mk2-equipment and gave it corresponding icon to be consistent with other technologies of this kind.

Personally I'd prefer it if all the equipment prototypes changed to follow the "personal-roboport-equipment-2" format to be consisted with other types of game prototypes and then the "MK" prefix can just be in the localisation (if it is needed at all).

Same. removing the -2 from the end and adding mk2 in the middle, well, it's always been confusing and annoying, more so since the non-contiguous issue was introduced. having a number suffix on all multi-level technologies would be preferable.
Plus this change will remove the 2 from the technology icon in the technology tree.

So, a bold search and destroy would look something like the following:

Code: Select all

s/get_inventory\(\s*defines.inventory.(?:player|god)_main\s*)/get_main_inventory()/g;
s/defines.inventory.player/defines.inventory.character/g;
s/power-armor-2/power-armor-mk2/g;
s/personal-roboport-equipment-2/personal-roboport-mk2-equipment/g;

The player -> character rename in the data phase is non-trivial to do with a simple search-and-replace, as there are so many different ways to reference data.raw.player.player.

since I add new character entities to the game, I iterate through data.raw.player a lot too. definitely a non-trivial issue for my mods.

[bobingabout]

• Renamed the character entity type and name from "player" to "character" to make it consistent with how we call/access it in all other places.

Just going through mod things... if a script checks for entity.type == "player", that's going to need to change to character too, right?

[Bilka]

Just going through mod things... if a script checks for entity.type == "player", that's going to need to change to character too, right?

Yes.

[orzelek]

This also means that game.player will be changed to game.character?

[Bilka]

This also means that game.player will be changed to game.character?

No. As said multiple time in this thread, the player -> character rename affects only the data stage (the prototype type and name) and the inventory defines.

The fact that there is so much confusion about this really shows that the difference between character and player is not clear. LuaPlayer/player is a concept - it's the player. The player can open guis, be printed to, etc. The character is only the little guy that is running around in the world, an entity. If you say "I want to damage the player" what you mean is "I want to damage the player's character" because the player is not a *thing*. The player can also not have a character - when you do /c game.player.character = nil, the player will move around using the god controller. Or it could be the spectator controller, if you set the player's controller to that.

TL;DR: Character = thing, player = concept.

[AmatorPhasma]

Okay, I'm a little confused, sorry that I need to ask :

But before:

Code: Select all

script.on_event(defines.events.on_entity_died, function(event) Event_on_entity_died(event) end)
function Event_on_entity_died(event)
    local entity = event.entity
    local cause = event.cause
    if cause then
        if cause.type == 'player' then
            local force = cause.player.force
            local character_name = cause.player.name
            local msg = {'apm_msg_storage_died', character_name}
            -- ...
        end
    end
end

And after this change:

Code: Select all

script.on_event(defines.events.on_entity_died, function(event) Event_on_entity_died(event) end)
function Event_on_entity_died(event)
    local entity = event.entity
    local cause = event.cause
    if cause then
        if cause.type == 'player' then
            local force = cause.character.force
            local character_name = cause.character.name
            local msg = {'apm_msg_storage_died', character_name}
            -- ...
        end
    end
end

right?

[Bilka]

No. As said multiple time in this thread, the player -> character rename affects only the data stage (the prototype type and name) and the inventory defines.

You missed the one thing that does change: you have to now check cause.type == "character" instead of cause.type == "player" - because this is the prototype type - which is what changed.

[bobingabout]

TL;DR: Character = thing, player = concept.

I'd revise that to...
Player = The Camera and Control Interface. (Keyboard, Mouse and Monitor)
Character = The man running around that you can see and control.

if if you want 1 word answers.
Character = Entity.
Player = Interface.

Okay, I'm a little confused, sorry that I need to ask :

But before:

Code: Select all

script.on_event(defines.events.on_entity_died, function(event) Event_on_entity_died(event) end)
function Event_on_entity_died(event)
    local entity = event.entity
    local cause = event.cause
    if cause then
        if cause.type == 'player' then
            local force = cause.player.force
            local character_name = cause.player.name
            local msg = {'apm_msg_storage_died', character_name}
            -- ...
        end
    end
end

And after this change:

Code: Select all

script.on_event(defines.events.on_entity_died, function(event) Event_on_entity_died(event) end)
function Event_on_entity_died(event)
    local entity = event.entity
    local cause = event.cause
    if cause then
        if cause.type == 'player' then
            local force = cause.character.force
            local character_name = cause.character.name
            local msg = {'apm_msg_storage_died', character_name}
            -- ...
        end
    end
end

right?

Code: Select all

script.on_event(defines.events.on_entity_died, function(event) Event_on_entity_died(event) end)
function Event_on_entity_died(event)
    local entity = event.entity
    local cause = event.cause
    if cause then
        if cause.type == 'character' then
            local force = cause.player.force
            local character_name = cause.player.name
            local msg = {'apm_msg_storage_died', character_name}
            -- ...
        end
    end
end

It shouldn't be this hard to understand.

[Earendel]

Is there an ETA for this update? I'm guessing afternoon.

[Pi-C]

With version 0.17.35 we are making a lot of changes that break mods. We want to give you the opportunity to prepare your mods for these changes, so we are already sharing the relevant parts of the changelog.

Breaking API changes
Modding (the data stage):

• Renamed the character entity type and name from "player" to "character" to make it consistent with how we call/access it in all other places.

Seems you have to take care of the directory structure, too. I just found this reason for one mod being disabled:

Code: Select all

File not found: __base__/graphics/entity/player/hr-level1_dead.png

The directory graphics/entity/player/ still exists, but is empty. Its contents has been moved to graphics/entity/character, so please make sure to also update file paths!

[H8UL]

Would it be possible to get a sticky post called something like "announcements for modders", for announcements like these?

There could still be a separate email, with a link in the announcements.

Benefit: Any mod author could then subscribe to it, and be notified of breaking changes. If mod authors are as time-constrained as me, this would be really beneficial, as I would have planned to be free Thursday night to test and patch up my mods.

[DaveMcW]

I think the LuaControl documentation still needs some cleanup work.

I know these properties also accept character, and there may be others:
vehicle
riding_state
driving

[Bilka]

I think the LuaControl documentation still needs some cleanup work.

I know these properties also accept character, and there may be others:
vehicle
riding_state
driving

LuaControl states that it is the common functions between LuaPlayer and LuaEntity when LuaEntity is a Character. This means that everything on that page works with characters. But given your post and the fact that you are not a noob, this is obviously not clear, so I want to improve that. Where would you look for this information? Is there something on that page which makes it seem like not all functions work with characters?

[H8UL]

...

Would it be possible to get a sticky post called something like "announcements for modders", for announcements like these?

There could still be a separate email, with a link in the announcements.

Benefit: Any mod author could then subscribe to it, and be notified of breaking changes. If mod authors are as time-constrained as me, this would be really beneficial, as I would have planned to be free Thursday night to test and patch up my mods.

Please excuse the pestering -- but wasn't sure if any forum mods had seen my suggestion?

[Koub]

Please excuse the pestering -- but wasn't sure if any forum mods had seen my suggestion?

I could have created the sticky you required, but right now, there's nothing I can warn about, there are no mod breaking changes annouced for a future release of Factorio.
I could have stickied this one, but ... that would have been too late