Small documentation improvement requests

Place to ask discuss and request the modding support of Factorio. Don't request mods here.
Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

I'd like some rephrasing:
https://lua-api.factorio.com/1.1.59/Lua ... nnections

"The fluidbox connections for the given fluidbox index."
This, I expected to be similar to pipe_connections of the fluidbox prototype:
https://lua-api.factorio.com/latest/Lua ... onnections
"The pipe connection points."

However, get_connections has nothing about pipe connections returned, which makes the description confusing. I think for get_connections(index), a much better phrasing is: "The fluidbox(es) to which the fluidbox at this index is connected."


-> Thanks for the detailed report, fixed for the next release.
I have mods! I guess!
Link

Xorimuth
Filter Inserter
Filter Inserter
Posts: 430
Joined: Sat Mar 02, 2019 9:39 pm
Contact:

Re: Small documentation improvement requests

Post by Xorimuth »

I've been informed that most commands that raise events now state that (e.g. https://lua-api.factorio.com/latest/Lua ... ted_entity).

Here's a few that are missing this information:

on_player_driving_changed_state:
https://lua-api.factorio.com/latest/Lua ... ol.driving
https://lua-api.factorio.com/latest/Lua ... set_driver

on_player_cursor_stack_changed
I'd have thought this would be raised from any API commands that change the cursor e.g.
https://lua-api.factorio.com/latest/Lua ... ear_cursor
Maybe it doesn't raise immediately - I've not tested if it interrupts execution.


-> Thanks for the details, those three do indeed raise events, which is noted for the next release. The driving one fire immediately, the cursor one at the end of the tick, fyi.

xfret
Manual Inserter
Manual Inserter
Posts: 1
Joined: Sun Apr 11, 2021 10:40 am
Contact:

Re: Small documentation improvement requests

Post by xfret »

In the documentation for the prototype Projectile (https://wiki.factorio.com/Prototype/Projectile), it states that the member "action" is of type Trigger. In the documentation for the type Trigger (https://wiki.factorio.com/Types/Trigger), it states that this type is an array of tables of type TriggerItem. In the prototype definition for "artillery-projectile", though, it appears to be a straight up TriggerItem itself (Image).

For the prototype definition for the Entity grenade, action seems to indeed be an array of tables of type TriggerItem (Image), so it appears it can be either. Should the doc be modified to reflect this or have I incorrectly inferred something?


-> Thank you for noticing this, Types/Trigger itself can either be one TriggerItem or an array of them. Noted!

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://lua-api.factorio.com/1.1.59/Lua ... place_this
a tile prototype's item_to_place_this can be nil, vs an empty table. I'd appreciate that being mentioned.

Code: Select all

/c
for k,v in pairs(game.tile_prototypes) do
	local items_to_place_this = v.items_to_place_this
	if not items_to_place_this then
		game.print(k.." has no items_to_place_this")
		break
	end
end
-> Sure, added for the next release.
Attachments
no_items_to_place_this.jpg
no_items_to_place_this.jpg (92.12 KiB) Viewed 751 times
I have mods! I guess!
Link

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://lua-api.factorio.com/1.1.59/Lua ... properties
Two underscores are missing in a tile prototypes mineable_properties:

Code: Select all

miningtime :: double
miningparticle :: string?

The LuaEntityPrototype -> mineable_properties do have them


-> These have been broken for a looong time, thanks! Fixed for the next release.
I have mods! I guess!
Link

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://lua-api.factorio.com/1.1.59/Lua ... ate_entity
highlight-box has an inaccurate bit for bounding_box

The bounding box defining the highlight box using absolute map coordinates. If specified, the position parameter is ignored, but needs to be present anyways. If not specified, the game falls back to the source parameter first, then the target parameter second. One of these three parameters need to be specified.
"If specified, the position parameter is ignored, but needs to be present anyways." I read (present tense) this as: "position is not necessary if bounding_box is not provided"

Code: Select all

/c
local player = game.player
local surface = player.surface
surface.create_entity{
	name = "highlight-box",
	target = player.character,
	time_to_live = 600,
}
Cannot execute command. Error: position not specified.

Code: Select all

/c
local player = game.player
local surface = player.surface
surface.create_entity{
	name = "highlight-box",
	position = {0,0},
	target = player.character,
	time_to_live = 600,
}

Success.

It seems position is always needed?


-> I'm not quite sure how you misunderstood the wording, I find it to be quite clear. The position parameter is ignored, yes, so it's not 'necessary', but it still needs to be present, ie not nil else the function will error. It's bad API design I guess, but the wording says what's happening. Either way, I rephrased it a bit for the next release.
I have mods! I guess!
Link

User avatar
Silari
Filter Inserter
Filter Inserter
Posts: 387
Joined: Sat Jan 27, 2018 10:04 pm
Contact:

Re: Small documentation improvement requests

Post by Silari »

Documentation for the Technology prototype's unit property's count_formula needs a word removed. https://wiki.factorio.com/Prototype/Technology#unit

[quote]"Formula that specifies how many units are needed per level of the infinite technology."[/quote]

That implies it only works on infinite techs, but count formula works perfectly fine on any technology, including infinite, finitely leveled, or non-leveled (upgrade=false, ie the default). Non-leveled techs just use 1 for the level.


-> Thank you Honktown for changing the wiki.

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

Silari wrote:
Sun Jun 05, 2022 9:15 pm
Documentation for the Technology prototype's unit property's count_formula needs a word removed. https://wiki.factorio.com/Prototype/Technology#unit
"Formula that specifies how many units are needed per level of the infinite technology."
That implies it only works on infinite techs, but count formula works perfectly fine on any technology, including infinite, finitely leveled, or non-leveled (upgrade=false, ie the default). Non-leveled techs just use 1 for the level.
Added information to the wiki. It will likely be reviewed and edited a little.

-> Thank you. No edits necessary :)
I have mods! I guess!
Link

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://lua-api.factorio.com/1.1.60/Lua ... ing_target

Writing nil is not supported. "Error: entity: table expected, got nil" I would get the impression it is (although the turret would probably immediately re-target that entity or another)

[RW]
Current description: "The shooting target for this turret or nil."
I have mods! I guess!
Link

lyvgbfh
Fast Inserter
Fast Inserter
Posts: 103
Joined: Fri Jul 10, 2020 6:48 pm
Contact:

Re: Small documentation improvement requests

Post by lyvgbfh »

Prototype/ArtilleryWagon has a proper description for `.gun` but Prototype/ArtilleryTurret claims gun is an "item".

https://wiki.factorio.com/Prototype/ArtilleryWagon
https://wiki.factorio.com/Prototype/ArtilleryTurret


-> Thank you Honktown for changing the wiki.

curiosity
Fast Inserter
Fast Inserter
Posts: 174
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

It should be noted in what units the various "emissions" runtime properties are. Pollution per second? Pollution per Joule? Something else entirely?
Last edited by curiosity on Sun Jun 12, 2022 3:02 pm, edited 1 time in total.

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

lyvgbfh wrote:
Tue Jun 07, 2022 10:17 am
Prototype/ArtilleryWagon has a proper description for `.gun` but Prototype/ArtilleryTurret claims gun is an "item".

https://wiki.factorio.com/Prototype/ArtilleryWagon
https://wiki.factorio.com/Prototype/ArtilleryTurret
Done ┐(´ー`)┌

-> Thanks (☞゚ヮ゚)☞
I have mods! I guess!
Link

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

What's the default build_check_type of surface.can_place_entity? default direction should be filled in too, presumably defines.direction.north.
I have mods! I guess!
Link

User avatar
Stringweasel
Fast Inserter
Fast Inserter
Posts: 101
Joined: Thu Apr 27, 2017 8:22 pm
Contact:

Re: Small documentation improvement requests

Post by Stringweasel »

IMO a note should be added to on_player_driving_changed_state.
This event is not raised when the vehicle is destroyed and the player consequently ejected.
It might be good to be explicit, because this is an undocumented recent change in the past few versions. See 102511 for reference.

User avatar
moon69
Fast Inserter
Fast Inserter
Posts: 173
Joined: Sun Sep 18, 2016 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by moon69 »

LuaSurface.create_entity documentation doesn't have advice for "stream" type entities.

It appears to be the same requirements as type "beam", but it would be nice to be sure.

User avatar
moon69
Fast Inserter
Fast Inserter
Posts: 173
Joined: Sun Sep 18, 2016 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by moon69 »

RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?


-> Thank you Honktown for adding this to the wiki.

User avatar
moon69
Fast Inserter
Fast Inserter
Posts: 173
Joined: Sun Sep 18, 2016 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by moon69 »

Prototype/Animation.layers documentation was copy/pasta from Types/Animation.layers and doesn't really make sense here.
layers
Type: table of Animation
If this property is present, all Animation definitions have to be placed as entries in the array, and they will all be loaded from there. Each item (Animation definition) in the array may also have the layers property.
If this property is present, all other properties are ignored and the mandatory properties do not have to be defined.

Layers may not be an empty table.
Since the only mandatory properties for Prototype/Animation.layers are 'name' & 'type', this gives...

Code: Select all

data:extend({
  {
    layers =
    {
      {
        name = "test-animation",
        type = "animation",
        animation_speed = 0.5,
        ...
The mandatory properties 'name' & 'type' I assume must be at the same level as 'layers' and are not ignored?
I think it should be like this?

Code: Select all

data:extend({
  {
    name = "test-animation",
    type = "animation",
    layers =
    {
      {
        animation_speed = 0.5,
        ...

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

moon69 wrote:
Tue Jun 14, 2022 11:01 am
RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?
Spawned children particles, to be clear? If you sign up for the wiki, you can make the edits yourself btw.

-> Thank you Honktown for adding this to the wiki.
I have mods! I guess!
Link

Honktown
Filter Inserter
Filter Inserter
Posts: 886
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

LuaForce.get_train_stops
The name parameter is the name of the stations, not the prototype. Please note.
I have mods! I guess!
Link

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

Re: Small documentation improvement requests

Post by Pi-C »

I've been wondering why my selection tool would find car prototypes although selection_mode was set to {"entity-with-owner"}. Turns out there is a bug in the prototype descriptions.

According to Prototype/Vehicle, vehicle prototypes are Prototype/EntityWithOwner:
Prototype definitions » PrototypeBase » Prototype/Entity » Prototype/EntityWithHealth » Prototype/EntityWithOwner » Prototype/Vehicle

However, Prototype/EntityWithOwner is missing from the descriptions of Prototype/Car and Prototype/SpiderVehicle.


Also, according to Prototype/RollingStock, rolling stock is Prototype/EntityWithOwner as well. But Prototype/EntityWithOwner is missing from the description of Prototype/ArtilleryWagon, Prototype/CargoWagon, and Prototype/FluidWagon (the description is correct for Prototype/Locomotive).
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Post Reply

Return to “Modding interface requests”