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

Place to post guides, observations, things related to modding that are not mods themselves.
Bilka
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by 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)
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

User avatar
Earendel
Factorio Staff
Factorio Staff
Posts: 711
Joined: Sun Nov 23, 2014 11:57 am
Contact:

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

Post by Earendel »

Bilka wrote:
Wed May 01, 2019 9:53 am
  • 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
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by 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!
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

User avatar
mrudat
Fast Inserter
Fast Inserter
Posts: 222
Joined: Fri Feb 16, 2018 5:21 am
Contact:

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

Post by 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
Filter Inserter
Filter Inserter
Posts: 509
Joined: Fri Apr 27, 2018 1:29 pm
Contact:

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

Post by Amarula »

Thank you!
My own personal Factorio super-power - running out of power.

User avatar
bobingabout
Smart Inserter
Smart Inserter
Posts: 7351
Joined: Fri May 09, 2014 1:01 pm
Contact:

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

Post by bobingabout »

Earendel wrote:
Wed May 01, 2019 10:10 am
Bilka wrote:
Wed May 01, 2019 9:53 am
  • 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.
mrudat wrote:
Wed May 01, 2019 12:34 pm
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.
Last edited by bobingabout on Wed May 01, 2019 1:19 pm, edited 1 time in total.
Creator of Bob's mods. Expanding your gameplay since version 0.9.8.
I also have a Patreon.

User avatar
bobingabout
Smart Inserter
Smart Inserter
Posts: 7351
Joined: Fri May 09, 2014 1:01 pm
Contact:

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

Post by bobingabout »

Bilka wrote:
Wed May 01, 2019 9:53 am
  • 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?
Creator of Bob's mods. Expanding your gameplay since version 0.9.8.
I also have a Patreon.

Bilka
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by Bilka »

bobingabout wrote:
Wed May 01, 2019 3:32 pm
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.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

orzelek
Smart Inserter
Smart Inserter
Posts: 3911
Joined: Fri Apr 03, 2015 10:20 am
Contact:

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

Post by orzelek »

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

Bilka
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by Bilka »

orzelek wrote:
Wed May 01, 2019 4:27 pm
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.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

User avatar
AmatorPhasma
Fast Inserter
Fast Inserter
Posts: 126
Joined: Sat Aug 05, 2017 8:20 pm
Contact:

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

Post by AmatorPhasma »

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

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
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by 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.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

User avatar
bobingabout
Smart Inserter
Smart Inserter
Posts: 7351
Joined: Fri May 09, 2014 1:01 pm
Contact:

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

Post by bobingabout »

Bilka wrote:
Wed May 01, 2019 4:52 pm
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.
AmatorPhasma wrote:
Wed May 01, 2019 7:04 pm
Okay, I'm a little confused, sorry that I need to ask :oops: :

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.
Creator of Bob's mods. Expanding your gameplay since version 0.9.8.
I also have a Patreon.

User avatar
Earendel
Factorio Staff
Factorio Staff
Posts: 711
Joined: Sun Nov 23, 2014 11:57 am
Contact:

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

Post by Earendel »

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

Pi-C
Smart Inserter
Smart Inserter
Posts: 1639
Joined: Sun Oct 14, 2018 8:13 am
Contact:

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

Post by Pi-C »

Bilka wrote:
Wed May 01, 2019 9:53 am
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!
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
H8UL
Fast Inserter
Fast Inserter
Posts: 114
Joined: Mon May 15, 2017 4:02 pm
Contact:

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

Post by 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.
Shameless mod plugging: Ribbon Maze

User avatar
DaveMcW
Smart Inserter
Smart Inserter
Posts: 3699
Joined: Tue May 13, 2014 11:06 am
Contact:

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

Post by 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
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

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

Post by Bilka »

DaveMcW wrote:
Sun May 05, 2019 1:27 am
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?
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

User avatar
H8UL
Fast Inserter
Fast Inserter
Posts: 114
Joined: Mon May 15, 2017 4:02 pm
Contact:

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

Post by H8UL »

Bilka wrote:
Sun May 05, 2019 7:27 am
...
H8UL wrote:
Sat May 04, 2019 7:45 am
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?
Shameless mod plugging: Ribbon Maze

Koub
Global Moderator
Global Moderator
Posts: 7175
Joined: Fri May 30, 2014 8:54 am
Contact:

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

Post by Koub »

H8UL wrote:
Thu May 09, 2019 8:50 am
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 :)
Koub - Please consider English is not my native language.

Post Reply

Return to “Modding discussion”