Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.
User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5206
Joined: Tue Jul 12, 2016 9:03 am
Contact:

Re: Small documentation improvement requests

Post by eradicator »

[M]y problem was on the prototype side though, trying to make a map preset. And couldn't figure out how to use autoplace_settings to limit allowed tile types. Gave up after a while... :/. Here's the smoking code ruin that remained:

Code: Select all

basic_settings = {
  autoplace_settings = {
    ['tile'] = {
      treat_missing_as_default = false,
      -- how does enforcing tiles work?
      --
      -- settings = {
      --   ['red-desert-03'] = { --is applied but has no effect?
      --     size = 100,
      --     frequency = 100,
      --     richness = 100,
      --     }
      --   }
      },
    }
  }
-> Disconnected from the MapSettings request, since https://wiki.factorio.com/Types/MapGenPreset does already list all properties. However autoplace_settings does need more docs to be added.

-> Thank you for pointing this out. The explanation for this from the runtime docs has now also been added to the wiki.
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.

andrei
Burner Inserter
Burner Inserter
Posts: 14
Joined: Tue Aug 27, 2019 8:32 pm
Contact:

Re: Small documentation improvement requests

Post by andrei »

My collection of questions/requests:
  • What does “not-stackable” Types/ItemPrototypeFlags add to having stack_size equal to 1?
  • Prototype/Item stack_size description says: “Must be 1 when stackable is false.” Would be clearer: “Must be 1 if has “not-stackable” flag.”
  • What does “not-selectable-in-game” Types/EntityPrototypeFlags add to having entity `selection_box = nil`? -> Now all explained on their respective pages, with a thank you to calcwizard for adding some of the info to the wiki.
  • Would be great if LuaEntity.health mentioned that max_health is available through `prototype.max_health`. I almost ended up computing it as `health / get_health_ratio()` *facepalm* -> Added for the next release
  • What is “secondary_draw_order” in Prototype/SimpleEntity? -> Added the explanation on all classes that use it.
  • Types/CollisionMask should mention `collision_mask_util.get_first_unused_layer` instead of “If a mod is going to use one of the unused layers it's recommended to start at the higher layers because the base game will take from the lower ones.” -> Added a note pointing to the library function.

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

Re: Small documentation improvement requests

Post by Silari »

andrei wrote:
Tue Jul 06, 2021 1:01 pm
There are several areas in the game where it ignores the stack size - artillery turrets (loads 15 shells in one slot) and assemblers (holds some multiple of the recipe requirement in a single slot) for instance off the top of my head. The flag prevents that too.

Mod edit, merging posts:

Found this in the 0.12 changelog:
Items now have a new optional attribute "stackable": When set to false, assembling machines won't be allowed to create stacks of the item. Currently only used with blueprints, to fix the "crafting machine stacks blueprints" bug.
So it was added specifically to avoid stacking blueprints in assemblers.

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

Klonan wrote:
Mon Jul 05, 2021 3:35 pm
...
I think I realized something stupid that might be worth mentioning in the docs anyway: if you start a request path from an entity position, with the entity's collision mask, it always fails (unless it doesn't collide with itself). That might be why I kept thinking the interpretation of a collision_mask was messed up.

The part about the array-to-value was how it is expressed. It appears people who prefer aren't as pedantic don't see any problem with the syntax of "array[string]". It's illogical when reading it, because an array does not work that way. []->string is better, or explicitly array->string. Was talking about it on the Discord, and some people had very strong opinions that any other appearance should be <T> (which is just arguing C++ is right, even though that's vector notation) or T[], which makes even less sense, because the returned value is before the array (more conventional to C-like declarations, maybe).
I have mods! I guess!
Link

User avatar
Klonan
Factorio Staff
Factorio Staff
Posts: 5148
Joined: Sun Jan 11, 2015 2:09 pm
Contact:

Re: Small documentation improvement requests

Post by Klonan »

Honktown wrote:
Tue Jul 06, 2021 11:31 pm
Klonan wrote:
Mon Jul 05, 2021 3:35 pm
...
I think I realized something stupid that might be worth mentioning in the docs anyway: if you start a request path from an entity position, with the entity's collision mask, it always fails (unless it doesn't collide with itself). That might be why I kept thinking the interpretation of a collision_mask was messed up.
This is why there is this:

Code: Select all

entity_to_ignore :: LuaEntity (optional): If given, the pathfind will ignore collisions with this entity.

posila
Factorio Staff
Factorio Staff
Posts: 5201
Joined: Thu Jun 11, 2015 1:35 pm
Contact:

Re: Small documentation improvement requests

Post by posila »

eradicator wrote:
Wed Jun 30, 2021 1:47 am
(I don't have a usecase for this, it's just one of these situations where I'm giving the doc a puzzled "wtf does this do" look.)

Prototype/Animation.mipmap_count and Prototype/Sprite.mipmap_count are documented as

Code: Select all

Only loaded if this is an icon (has flag "group=icon" or "group=gui"). 
but I don't see any prototype that uses Animation as an icon, and the doc says there's no inheritance between Animation and Sprite. So is this some sort of future-compatibility thing? Or a copy/paste error?
No animation has icon or gui flags by default, but it is still possible to set flags = { "icon" } in the animation definition. Animation is an array of sprites so that's how animations "inherit" sprite properties. But it is true, mipmap_count doesn't make sense in animation, as it is not possible to layout mipmaps in a way, that would load correctly both the animation and the mipmaps (besides animations with just one frame)

PFQNiet
Filter Inserter
Filter Inserter
Posts: 289
Joined: Sat Sep 05, 2020 7:48 pm
Contact:

Re: Small documentation improvement requests

Post by PFQNiet »

What is LuaEntity#is_crafting() supposed to check?

I expected it to return true if the machine is currently gaining progress, ie. is "working" or at the very least "low-power".

However, it seems to return true even on fuel-powered machines that stop working due to a lack of fuel.

Could the documentation be updated to clarify what exactly this function is checking?


-> This method actually indicates whether any crafting process has been started, meaning whether any progress on a craft has been made. It doesn't indicate whether the craft is currently progressing. I noted this for the next release, thanks for the hint.

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

Re: Small documentation improvement requests

Post by Pi-C »

I'm wondering about LuaSectorScannedEventFilter:
Depending on the value of filter, the table may take additional fields. filter may be one of the following:

"ghost"
"rail"
"rail-signal"
"rolling-stock"
"robot-with-logistics-interface"
"vehicle"
"turret"
"crafting-machine"
"wall-connectable"
"transport-belt-connectable"
"circuit-network-connectable"
"type": Additional fields:
type :: string: The prototype type
"name": Additional fields:
name :: string: The prototype name
"ghost_type": Additional fields:
type :: string: The ghost prototype type
"ghost_name": Additional fields:
name :: string: The ghost prototype name
Do any of the filters but "name" really make sense? I believe only radars can scan sectors, which would make the "type" filter redundant. Ghosted radars can't scan anything at all yet, so "ghost_type" and "ghost_name" shouldn't be needed. And the filters listed above "type" seem to be just a copy/paste error …

-> You are right that most of those filters are superfluous, since on_sector_scanned only fires for entities of type 'radar'. Fixing this however is not easy technically, which is why it will have to be the way it is for a while longer. Thanks for brining it up though.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://lua-api.factorio.com/latest/LuaControl.html

Code: Select all

get_personal_logistic_slot(slot_index) → PersonalLogisticParameters	Sets the personal request and trash to the given values.
get_vehicle_logistic_slot(slot_index) → PersonalLogisticParameters	Sets the vehicle logistic request and trash to the given values.
The description is clearly wrong.

-> You are clearly right, thanks for the hint. Fixed for the next release.
I have mods! I guess!
Link

curiosity
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

I think that the new LuaPlayer::start_selection can benefit from some clarifications:
- if there is an ongoing selection in any mode, that selection's starting point is set to the specified position; the mode isn't changed and selection continues as normal;
- if there is no ongoing selection, an area will be selected immediately in the specified mode between current cursor position and the specified position.


-> I think this goes into too much detail on how the API works, the current description is fine.

It should be documented somewhere how grid position in blueprints is calculated (see this post).

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

https://wiki.factorio.com/Prototype/Shortcut
I don't understand the difference between the 'normal' icons and the small ones:
icon
small_icon
disabled_icon
disabled_small_icon

[attachment=0]smallbig_reduced.jpg[/attachment]


Added this myself :) . Also added the scaled-to icon size (for a shortcut button).
Attachments
smallbig_reduced.jpg
smallbig_reduced.jpg (14.57 KiB) Viewed 4510 times
Last edited by Honktown on Sun Jul 18, 2021 2:27 pm, edited 1 time in total.
I have mods! I guess!
Link

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

Re: Small documentation improvement requests

Post by Xorimuth »

Honktown wrote:
Sat Jul 17, 2021 5:48 pm
https://wiki.factorio.com/Prototype/Shortcut
I don't understand the difference between the 'normal' icons and the small ones:
icon
small_icon
disabled_icon
disabled_small_icon

smallbig_reduced.jpg
Yes your guess is correct. And the disabled ones are the light gray icons at the same sizes.

Note that if you don't provide disabled_small_icon then it will downscale from icon instead of disabled_icon (viewtopic.php?f=28&t=91598) I've just added default information to the wiki as well.
Last edited by Xorimuth on Sun Jul 18, 2021 9:34 pm, edited 1 time in total.
My mods
Content: Freight Forwarding | Spidertron Patrols | Spidertron Enhancements | Power Overload
QoL: Factory Search | Remote Configuration | Module Inserter Simplified | Wire Shortcuts X | Ghost Warnings

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

Re: Small documentation improvement requests

Post by Silari »

https://lua-api.factorio.com/latest/Lua ... n_settings has two issues
The generation settings for the surface.

can be used to adjust the surface after changing generation settings.

Note: When changing settings runtime the game will not retroactively change anything.
Note: LuaSurface::regenerate_entity, LuaSurface::regenerate_decorative, and LuaSurface::delete_chunk
Second line needs 'Can' capitalized, or arguably 'This' added to the beginning would be better.

The second note is nonsensical. It links to the three functions but doesn't say how any of them are related to map_gen_settings. I can sorta guess it might be referring to the previous note, in that using the regenerate functions can make changes appear on old chunks (and deleting a chunk will regen it with the new settings when it's remade), but it's really not clear. If that is the case those functions should just be in the previous note as a new sentence of 'You can force regeneration of chunks with these functions'.


-> This looked weird because of a formatting error in the interal docs, the 'can ...' part was intended to be part of the second note. I reworded the whole thing for the next release, thanks for the hint.

PFQNiet
Filter Inserter
Filter Inserter
Posts: 289
Joined: Sat Sep 05, 2020 7:48 pm
Contact:

Re: Small documentation improvement requests

Post by PFQNiet »

The name last_user implies it updates when someone uses the entity. But it is described as "the player who built the entity". But it is read-write. And it changes on assemblers when the recipe is changed. Also it can be nil.

Basically, it's woefully inadequate in its documentation right now!


-> Thanks for the hint, I've updated the description for the next release.

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

Re: Small documentation improvement requests

Post by Pi-C »

How exactly does direction_deviation (ProjectileTriggerDelivery) work? Is it a probability that the projectile will deviate from its target, or does it specify an angle? I didn't notice a difference between setting it to 5 or 1.5.
-> Documented on the wiki, thank you Klonan and Honktown for gathering some of the info.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
Klonan
Factorio Staff
Factorio Staff
Posts: 5148
Joined: Sun Jan 11, 2015 2:09 pm
Contact:

Re: Small documentation improvement requests

Post by Klonan »

Pi-C wrote:
Sun Jul 18, 2021 10:12 am
How exactly does direction_deviation (ProjectileTriggerDelivery) work? Is it a probability that the projectile will deviate from its target, or does it specify an angle? I didn't notice a difference between setting it to 5 or 1.5.
Its the deviation of the angle, in orientation units (0 - 1)

so setting it to 1 or above means basically 360 degree random spread (+/- 0.5 orientation aka +/- 180 degrees)

For instance the shotgun has a deviation of 0.3, so +-/0.15 orientation either direction from the origin orientation


-> It's in radians, see viewtopic.php?p=549677#p549677

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

Re: Small documentation improvement requests

Post by Pi-C »

Klonan wrote:
Sun Jul 18, 2021 6:23 pm
Thanks for the explanation! This info should definitely be added to the documentation. It helped me tremendously to get my projectiles working as expected: My basic ammo is missing its target occasionally, but not flying in the opposite direction. :-)

Also regarding ProjectileTriggerDelivery: If range_deviation is set, could a projectile fly a distance smaller than min_range or exceeding max_range, or are these values hard limits?

-> Documented on the wiki, thank you Klonan and Honktown for gathering some of the info.

Generally, I'd appreciate if the documentation would contain some examples for sane values. If a variable takes a string, uint, or Boolean value, that's pretty much self-explaining. But floating point values? They could be used as a factor (e.g. it would make sense to have a speed modifier of 2.5 to increase the speed to 250% of the default value), but it's also possible that only values between 0 and 1 are reasonable (e.g. for percentages, or for fractions of a full circle).

-> Good point! The same as the general thread goes here: Please give us the specific cases to run into, so we can prioritize adding this info to them.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
snouz
Inserter
Inserter
Posts: 27
Joined: Sun Jan 03, 2021 6:01 pm
Contact:

Re: Small documentation improvement requests

Post by snouz »

I found some errors in: https://wiki.factorio.com/Types/IconData

According to my tests, the default scale seems to be 0.5 for recipe icons. When you force a scale of 1, they'll appear twice as big on the alt mode. I haven't checked 32px icons, since all vanillas are 64. I can make a test if needed.

Also, it could be made clearer that the shift of subsequent icons in "icons" is (I believe) based on (scale * size) of the first icon in "icons". For default icons, that is (0.5 * 64) so 32 (but if your first icon is scale 1 size 64, shift of every icon is based on 64)

Also, I believe the default tint isn't {r=0, g=0, b=0, a=1}, as this is completely opaque black (as confirmed by my tests). It's apparently the opposite, {r=1, g=1, b=1, a=0}.

It could also be made clear that the shadow behind the icons is drawn based on the shape of the FIRST icon in icons (as tested by my script which originally used a transparent image as a first layer, and thus there would be no shadow at all in the menu or on entities)

ctrl maj f on an icon I created, with no defined scale or tint:

Image

EDIT: got a wiki account, ran some tests and made the IconData page more precise.
Last edited by snouz on Sat Aug 07, 2021 10:14 pm, edited 2 times in total.
Graphically contributed to : Bio Industries (soon) | Warehousing | MFerrari's mods | Brevven's mods | Bob Artisanal Reskins | Mining Drones | Teleporters | Emoji signals

curiosity
Filter Inserter
Filter Inserter
Posts: 315
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

IDK where, but this should be documented:
Honktown@discord wrote:orders are optional
A nil turns into "" somewhere?
boskid@discord wrote:you are right, they are optional
which means if you provide a nil, on the c++ side they will be loaded with some default
which for orderString is an empty string (with some exceptions for TipsAndTricksItem and TutorialDefinition where the name is used as a default instead)
Source: https://discord.com/channels/1396775903 ... 2785441842

-> Documented at https://wiki.factorio.com/PrototypeBase#order. Differing defaults given by boskid aren't documented since the game falls back to names for comparison anyway. However, there is another differing default at https://wiki.factorio.com/Prototype/Nam ... Expression (documented)

Honktown
Smart Inserter
Smart Inserter
Posts: 1025
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

Klonan wrote:
Sun Jul 18, 2021 6:23 pm
Its the deviation of the angle, in orientation units (0 - 1)

so setting it to 1 or above means basically 360 degree random spread (+/- 0.5 orientation aka +/- 180 degrees)

For instance the shotgun has a deviation of 0.3, so +-/0.15 orientation either direction from the origin orientation
It's +/- radians / 2, actually. Edit: I added information to the wiki.

Embedded images:
Examples
Last edited by Honktown on Mon Jul 19, 2021 5:28 am, edited 1 time in total.
I have mods! I guess!
Link

Locked

Return to “Documentation Improvement Requests”