Somethings not (or hidden) in doc but you need to know

Place to post guides, observations, things related to modding that are not mods themselves.
User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

It has been some time since I've started modding for Factorio. There's something that happens quite often: wow, so I can / cannot do this? I wish someone had told me before!
Many hours have been wasted and we should avoid this. So, I would like to list the things that are not documented, or well hidden in the documents, so we don't make the same mistakes again.

Starting from the basic ones in data phase to the things about control phase:
Data
Prototype naming
Error - invalid prototype array nil
Only some entity types support apply_runtime_tint
Solution to incorrect icon size
Max image size
Icon tinting, Multi-layered icon
How to use data.raw
fast_replaceable_group is not the magic solution
order is not black magic
player-port is special
Large maximum_wire_distance can cause lag
stream projectile particle_buffer_size has to be at least 2
cluster_count has to be at least 2
push-back effect takes the target entity collider size into account
Data and Control
Data structure in data vs control
Code accessibility in data vs control
Useful functions and libraries
LuaEntityPrototype.collision_mask does not return not-colliding-with-itself
Control
The global table
Only one handler for each event
GUI Naming
Setting player.character
How to order deconstruct tiles
The cause in on_entity_died does not always work
Find entity using position will not return entities without collider
The Mod Portal
Character limit
New Portal
Feel free to contribute if you know more and you think that should be added. :)
Last edited by Mooncat on Wed Sep 06, 2017 7:23 am, edited 22 times in total.

User avatar
darkfrei
Smart Inserter
Smart Inserter
Posts: 2903
Joined: Thu Nov 20, 2014 11:11 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by darkfrei »

It would be nice to know, that functions in data.lua must be early than calling of this functions. By control.lua it's not important.

Nexela
Smart Inserter
Smart Inserter
Posts: 1828
Joined: Wed May 25, 2016 11:09 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Nexela »

darkfrei wrote:It would be nice to know, that functions in data.lua must be early than calling of this functions. By control.lua it's not important.
Not sure what you are trying to say here.

d3x0r
Filter Inserter
Filter Inserter
Posts: 316
Joined: Sun Jun 04, 2017 8:56 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by d3x0r »

darkfrei wrote:It would be nice to know, that functions in data.lua must be early than calling of this functions. By control.lua it's not important.
it is important still of you specify 'local' on the function.

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

d3x0r wrote:
darkfrei wrote:It would be nice to know, that functions in data.lua must be early than calling of this functions. By control.lua it's not important.
it is important still of you specify 'local' on the function.
I think I understand what you meant.
Added "CODE ACCESSIBILITY IN DATA VS CONTROL". ;)

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

Re: Somethings not (or hidden) in doc but you need to know

Post by Koub »

I am no modder, so I'm not sure how overwhelmingly useful all these tips are, but I guess it's the kind of stuff that should be stickied, so that it doesn't disappear in the mysterious deapths of the forum, where there be biters lurking, and stuff.
[Koub] Stickied.
Koub - Please consider English is not my native language.

User avatar
Optera
Smart Inserter
Smart Inserter
Posts: 2915
Joined: Sat Jun 11, 2016 6:41 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Optera »

Very useful compendium.
It contains a lot of things I stumbled across myself.

Here's another peculiarity that broke a lot of my mods when transitioning from 0.14 to 0.15.
Variable paths can conflict between mods

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

Koub wrote:I am no modder, so I'm not sure how overwhelmingly useful all these tips are, but I guess it's the kind of stuff that should be stickied, so that it doesn't disappear in the mysterious deapths of the forum, where there be biters lurking, and stuff.
[Koub] Stickied.
Thanks! I'm sure this will help a lot of people. :D
Optera wrote:Very useful compendium.
It contains a lot of things I stumbled across myself.

Here's another peculiarity that broke a lot of my mods when transitioning from 0.14 to 0.15.
Variable paths can conflict between mods
I tried but couldn't reproduce. :?
But there is a slight difference: my mod names don't use underscore (_) but hyphen (-). Don't know if that matters. Don't know why even if so.
Are you really sure MOD_NAME = "my_mod"?

User avatar
Optera
Smart Inserter
Smart Inserter
Posts: 2915
Joined: Sat Jun 11, 2016 6:41 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Optera »

Mooncat wrote:I tried but couldn't reproduce. :?
But there is a slight difference: my mod names don't use underscore (_) but hyphen (-). Don't know if that matters. Don't know why even if so.
Are you really sure MOD_NAME = "my_mod"?
It seemed to be quite a problem for some users of my mods. I couldn't reproduce it myself either, maybe they where haphazardly repacking them into modpacks. :roll:
After changing my paths to static strings all complaints stopped entirely.

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

Optera wrote:
Mooncat wrote:I tried but couldn't reproduce. :?
But there is a slight difference: my mod names don't use underscore (_) but hyphen (-). Don't know if that matters. Don't know why even if so.
Are you really sure MOD_NAME = "my_mod"?
It seemed to be quite a problem for some users of my mods. I couldn't reproduce it myself either, maybe they where haphazardly repacking them into modpacks. :roll:
After changing my paths to static strings all complaints stopped entirely.
I can't add if I can't verify it. Sorry. :(

Nexela
Smart Inserter
Smart Inserter
Posts: 1828
Joined: Wed May 25, 2016 11:09 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Nexela »

Optera wrote:Very useful compendium.
It contains a lot of things I stumbled across myself.

Here's another peculiarity that broke a lot of my mods when transitioning from 0.14 to 0.15.
Variable paths can conflict between mods

The reason this broke is explaind in CODE ACCESSIBILITY IN DATA VS CONTROL

You are setting a global variable with a generic name MOD_NAME in the data stage.
Mod B is now setting the same variable with their mod name
When data-updates time rolls around MOD_NAME is set to Mod B's name


The solution(s) in order of preference
1. local all the damn things
2. Use a less generic var name LTN_PATH

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

Ah, yes! That can explain it.

User avatar
Optera
Smart Inserter
Smart Inserter
Posts: 2915
Joined: Sat Jun 11, 2016 6:41 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Optera »

Nexela wrote:
Optera wrote:Very useful compendium.
It contains a lot of things I stumbled across myself.

Here's another peculiarity that broke a lot of my mods when transitioning from 0.14 to 0.15.
Variable paths can conflict between mods

The reason this broke is explaind in CODE ACCESSIBILITY IN DATA VS CONTROL

You are setting a global variable with a generic name MOD_NAME in the data stage.
Mod B is now setting the same variable with their mod name
When data-updates time rolls around MOD_NAME is set to Mod B's name


The solution(s) in order of preference
1. local all the damn things
2. Use a less generic var name LTN_PATH
Thanks, that explains it.

You might want to explicitly state variables used in config.lua should have an unique prefix like prototype names. Localizing those variables makes no sense, but they they should be prone to overwrite each other.

Nexela
Smart Inserter
Smart Inserter
Posts: 1828
Joined: Wed May 25, 2016 11:09 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Nexela »

config.lua is just a lua file and the recommendation is to treat it like all other lua modules.

config.lua

Code: Select all

local config = {}
config.a = "a"
config.b = "b"
return config

otherfile.lua

Code: Select all

local config = require 'config'
if config.a then print config.b end

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

Added some new topics these few days:

Data:
  • Error - invalid prototype array nil
  • Solution to incorrect icon size
  • Max image size
  • Icon tinting, multi-layered icon
  • Large maximum_wire_distance can cause lag
  • Stream projectile particle_buffer_size has to be at least 2
  • cluster_count has to be at least 2
Control:
  • Only one handler for each event
  • How to order deconstruct tiles
  • The cause in on_entity_died does not always work
The Mod Portal:
  • Character limit
  • New portal

User avatar
Mooncat
Smart Inserter
Smart Inserter
Posts: 1190
Joined: Wed May 18, 2016 4:55 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by Mooncat »

Added the following info:
Data: push-back effect takes the target entity collider size into account
Control: Find entity using position will not return entities without collider

Also improved:
Data: Stream projectile particle_buffer_size has to be at least 2

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by eradicator »

New modders often seem to misunderstand why "function() end" is often used when registering event handlers and use it wrongly (this is more of a generic lua thing than factorio specific tho).

For example mods i look at often do something like this:

Code: Select all

local function my_tick_handler(event)
  --stuff
  end

script.on_event(defines.events.on_tick, function(event) my_tick_handler(event) end)

instead of just

Code: Select all

script.on_event(defines.events.on_tick,my_tick_handler)
So they create an unnessecary wrapper function when they already have a seperate handler function.
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

User avatar
darkfrei
Smart Inserter
Smart Inserter
Posts: 2903
Joined: Thu Nov 20, 2014 11:11 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by darkfrei »

eradicator wrote:New modders often seem to misunderstand why "function() end" is often used when registering event handlers and use it wrongly (this is more of a generic lua thing than factorio specific tho).
So they create an unnessecary wrapper function when they already have a seperate handler function.
And when I need two handlers?

Code: Select all

function first_tick_handler(event)
-- first part
end

function second_tick_handler(event)
-- second part
end

script.on_event(defines.events.on_tick, function(event) 
first_tick_handler(event) 
second_tick_handler(event) 
end)
Last edited by darkfrei on Mon Aug 28, 2017 8:14 am, edited 1 time in total.

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by eradicator »

darkfrei wrote:And when I need two handlers?
Then you do what you just said.
My point was the erroneous usage when the extra wrapper is added just because the new modder saw someone else do it like that and they didn't understand why that works. Also if you have two different tick handlers for the same thing you should probably combine them ;P.

Edit:

Oh an while talking about tick handlers, the often used "if event.tick % 60 == 0" can be slightly improved by using semi-random numbers instead, e.g. ""if event.tick % 61 == 42", this makes it less likely that several mods end up doing their handler on the same tick. As long as the tick handler isn't really heavy this won't make a huge differnce tho. But processing spikes are something to be kept in mind when dealing with on_tick.
Author of: Belt Planner, Hand Crank Generator, Screenshot Maker, /sudo and more.
Mod support languages: 日本語, Deutsch, English
My code in the post above is dedicated to the public domain under CC0.

User avatar
darkfrei
Smart Inserter
Smart Inserter
Posts: 2903
Joined: Thu Nov 20, 2014 11:11 pm
Contact:

Re: Somethings not (or hidden) in doc but you need to know

Post by darkfrei »

Why in control.lua can be that:

Code: Select all

function foo(event)
-- code here
end

script.on_event(defines.events.on_tick, function(event) 
foo(event) 
bar(event) 
end)

function foo(event)
-- code here
end
But in data.lua it don't works?

Code: Select all

function foo(data)
-- code here
end

foo(data) 
bar(data) 

function foo(data)
-- code here
end
Here function must be early than calling of it.

Post Reply

Return to “Modding discussion”