Small documentation improvement requests

Place to ask discuss and request the modding support of Factorio. Don't request mods here.
PFQNiet
Fast Inserter
Fast Inserter
Posts: 238
Joined: Sat Sep 05, 2020 7:48 pm
Contact:

Re: Small documentation improvement requests

Post by PFQNiet »

Why do I have to dig through the game files to find what fields exist on MapSettings?

(Perhaps more importantly, this prevents them from appearing in runtime-api.json, causing "undefined property" warnings when using them.)


-> I finally got around to trudging through this, the concept will be properly documented in a future release.

curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 79
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

on_console_chat event doesn't capture /shout. Does it also not capture any other command-like messages? This should be clarified and noted in the docs.

-> Thanks, noted for the next release.

User avatar
eradicator
Smart Inserter
Smart Inserter
Posts: 5201
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.
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
Fast Inserter
Fast Inserter
Posts: 245
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
Filter Inserter
Filter Inserter
Posts: 822
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: 4957
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: 5085
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
Fast Inserter
Fast Inserter
Posts: 238
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: 1096
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
Filter Inserter
Filter Inserter
Posts: 822
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
Long Handed Inserter
Long Handed Inserter
Posts: 79
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
Filter Inserter
Filter Inserter
Posts: 822
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 593 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: 329
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.

curiosity
Long Handed Inserter
Long Handed Inserter
Posts: 79
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

https://lua-api.factorio.com/latest/Concepts.html#BlueprintEntity mentions BlueprintCircuitConnection and BlueprintControlBehavior, but there are no links and they are nowhere to be seen.

-> Yep, they are not documented yet. It's on the list.

User avatar
Silari
Fast Inserter
Fast Inserter
Posts: 245
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
Fast Inserter
Fast Inserter
Posts: 238
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: 1096
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: 4957
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: 1096
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!

Post Reply

Return to “Modding interface requests”