Documentation Improvement Requests

[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.

[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.

[Silari]

• What does “not-stackable” Types/ItemPrototypeFlags add to having stack_size equal to 1?

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]

...

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).

[Klonan]

...

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]

(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]

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]

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.

[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.

[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]

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).

[Xorimuth]

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.

[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]

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]

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.

[Klonan]

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]

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.

[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:


EDIT: got a wiki account, ran some tests and made the IconData page more precise.

[curiosity]

IDK where, but this should be documented:

orders are optional
A nil turns into "" somewhere?

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]

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

This is what 2 looks like, aka +/- ~57 degrees:

deviation_2.jpg (354.83 KiB) Viewed 6398 times

3.14, +/- 90 degrees:

deviation_3.14.jpg (387.79 KiB) Viewed 6398 times

and 6.28, aka weeeeeeee:

deviation_6.28.jpg (472.94 KiB) Viewed 6398 times