wiki prototype docs - why do you still use them? | Factorio | Page 1

topaz hill Dec 13, 2023, 8:25 AM

#

let's thread it

cedar tapir Dec 13, 2023, 8:26 AM

#

One thing I liked on the wiki was related concepts being on one page, for certain things. [An] example I ran into earlier tonight, energy sources

jaunty mango Dec 13, 2023, 8:26 AM

#

Force of habit

topaz hill Dec 13, 2023, 8:28 AM

#

cedar tapir One thing I liked on the wiki was related concepts being on one page, for certai...

I see, that unfortunately is unlikely to change. Does it not help that the inherited properties are on the page of the child? I find that it helps a lot for example with style specifications or triggers, which were already separate pages on the wiki

cedar tapir Dec 13, 2023, 8:30 AM

#

Hmm.

#

I can think of things on site layout that may be easier to talk about

#

One, above the search box, if Prototypes / Runtime were right there

#

It might not be something normally noticed, but not having it right there, where it feels like it matters the most, is a big oversight

#

When the docs were moved to the api page, I usually would pull up a specific page like I used to - LuaEntity, LuaSurface, LuaBootstrap, etc, but I honestly didn't find an obvious way to just make prototypes happen

topaz hill Dec 13, 2023, 8:37 AM

#

cedar tapir It might not be something normally noticed, but not having it *right there*, whe...

for an indication where you are or to switch stage?

#

(or both, but primary reason is..?)

cedar tapir Dec 13, 2023, 8:37 AM

#

To switch, and to make it obvious if I search for something, I won't find other results

#

The first time someone searches they might look for, let's say, inserter

#

And it just won't have the inserter prototype unless they knew to be on the main prototype pages

#

The prototype side, so to speak

topaz hill Dec 13, 2023, 8:40 AM

#

I see where you're coming from. It'd be a larger change, but it might be possible from a technical standpoint to let you search the other stage from the side, with a switch. Like say, you type inserter on the runtime sidebar, find nothing and it offers "search prototype docs instead"

cedar tapir Dec 13, 2023, 8:41 AM

#

From a design standpoint, it would be most obvious if they looked like in-game tabs, one saying Runtime, the other saying Prototype... I know the API isn't designed from the game's elements, but I think you understand what I mean

#

From the user-side, I think navigating between Prototypes and Runtime would be much much easier to use if the search was "separate-able" from what you're on, in that sense

#

So if someone looks up LuaEntity, and asks about a prototype, someone can say look for X in prototypes, and the search can just do that - without needing to "switch sides" of the API

topaz hill Dec 13, 2023, 8:45 AM

#

I'm still hesitant to connect the two stages too much, but connecting the search partially (like you propose) sounds intuitive to me. Because you'd still need to manually switch so the separation should hopefully stay clear

cedar tapir Dec 13, 2023, 8:46 AM

#

The actual pages going back and forth is acceptable to me, as that makes complete sense. You leave a Runtime page and are now on a Prototype page

#

The search being "bound" to which side you're on without an easy way to go back and forth... not very intuitive

topaz hill Dec 13, 2023, 8:48 AM

#

I don't find myself going back and forth much, so it hasn't been in my radar. So it's good to hear this from other, after all the page is for all modders, not just my usecases

cedar tapir Dec 13, 2023, 8:49 AM

#

Moving on from that topic, if we may

#

One possible thing to "clean" the layout a bit, might be a way to minimize the "short descriptions" that are in the main Members / Properties tables

#

To keep things simple, say a global or per-side user option... I'm outdated and think of just a cookie setting

#

Compare the density and brevity of:

Prototype/Inserter — inserter
energy_source    ::    EnergySource
extension_speed    ::    double
hand_base_picture    ::    Sprite
hand_base_shadow    ::    Sprite
hand_closed_picture    ::    Sprite
hand_closed_shadow    ::    Sprite
hand_open_picture    ::    Sprite
hand_open_shadow    ::    Sprite
insert_position    ::    vector
pickup_position    ::    vector
platform_picture    ::    Sprite4Way
rotation_speed    ::    double
allow_burner_leech    ::    bool (optional)
allow_custom_vectors    ::    bool (optional)
chases_belt_items    ::    bool (optional)
...

#

vs

extension_speed    :: double
rotation_speed    :: double
insert_position    :: Vector
pickup_position    :: Vector
platform_picture    :: Sprite4Way
hand_base_picture    :: Sprite
hand_open_picture    :: Sprite
hand_closed_picture    :: Sprite
energy_source    :: EnergySource

Defines how this inserter gets energy.
energy_per_movement optional     :: Energy
energy_per_rotation optional     :: Energy
stack optional     :: bool

Whether this inserter is considered a stack inserter.
allow_custom_vectors optional     :: bool

Whether pickup and insert position can be set run-time.
allow_burner_leech optional     :: bool

Whether this burner inserter can fuel itself from the fuel inventory of the entity it is picking up items from.
draw_held_item optional     :: bool

Whether the item that the inserter is holding should be drawn.
use_easter_egg optional     :: bool

#

I understand the intent of having short descriptions, but it interrupts the idea that this is a list of things one can examine closely

topaz hill Dec 13, 2023, 8:53 AM

#

haha, that matches my thought of "what if we removed the short descriptions from the TOC to force people to read the whole description. nah, that sounds like a bad idea" I had yesterday

cedar tapir Dec 13, 2023, 8:54 AM

#

Honestly, I think that's a better way to handle it

#

It reduces where the information is, so it's easier to manage and easier for the user to find what and to know where it would be

#

As I understand simple HTML, the text can be made hidden but still come up with ctrl-f searches. I don't know how it interacts with expanding nodes or however it is called

#

A reduced layout is a small step, moving information is the bigger one

topaz hill Dec 13, 2023, 8:57 AM

#

now, fun question. If you expand the layout to fill the whole page (button top right) and the descriptions end up on the side, how much does that improve the readability of the list for you?

cedar tapir Dec 13, 2023, 8:57 AM

#

.......how did you know I did not know about the expand layout trianglepupper

topaz hill Dec 13, 2023, 8:57 AM

#

just a guess trianglepupper

cedar tapir Dec 13, 2023, 8:57 AM

#

That or I tried it before and it got reset somewhere

#

Well. Hm. That's a thing isn't it

#

It doesn't interrupt the vertical flow

topaz hill Dec 13, 2023, 8:58 AM

#

I like it but then I want the sidebar so I open the sidebar and it squishes the TOC again and I just end up going boskid_think

cedar tapir Dec 13, 2023, 8:58 AM

#

Hm? The left search thing?

#

I'm on a UHD screen so my layout might be different

topaz hill Dec 13, 2023, 8:59 AM

#

yeah. on 1080p the wide layout + sidebar open still ends up with the descriptions in the extra row

#

.. or not?

cedar tapir Dec 13, 2023, 9:00 AM

#

A more intense option which might be "nice"... remove the repeated parts of classes etc from the search

#

Do I really need to see every prototype is a prototype

topaz hill Dec 13, 2023, 9:01 AM

#

not all prototypes are named XPrototype :(

#

some types are named XPrototype :((

cedar tapir Dec 13, 2023, 9:01 AM

#

Still, it could go a bit to improving the use of space

#

Some way to squash them... I need to mention something before I forget it

topaz hill Dec 13, 2023, 9:02 AM

#

I dont know, it doesnt make the sidebar wider to have the word there

cedar tapir Dec 13, 2023, 9:03 AM

#

One comparison to the wiki, the inheritance tree is a little harder to follow

#

The wiki goes from ancestor -> descendant. There is, also, that Prototype is at the end of the word instead of the front, which feels like it interrupts the flow of the text

#

I think "Inherits From" could be completely removed, and if the order were reversed, it'd be... more readable. And usable. It almost feels like I don't want to use anything there because it is difficult to read (?)

topaz hill Dec 13, 2023, 9:06 AM

#

you mean the list at the top of the page? Inherits from EntityWithOwnerPrototype « EntityWithHealthPrototype « EntityPrototype « PrototypeBase

cedar tapir Dec 13, 2023, 9:07 AM

#

Inherits from EntityWithOwnerPrototype « EntityWithHealthPrototype « EntityPrototype « PrototypeBase

PrototypeBase » Prototype/Entity » Prototype/EntityWithHealth » Prototype/EntityWithOwner » Prototype/Inserter

#

Both convey the same information, but it feels like the second presentation is just much easier to read and follow

#

Even just reversing the order and removing "Inherits from"

PrototypeBase >> EntityPrototype >> EntityWithHealthPrototype >> EntityWithOwnerPrototype

In a sense, from left-to-right follows where one starts, to where one ends up

#

to where one proceeds engithink

topaz hill Dec 13, 2023, 9:11 AM

#

the ordering was something we weren't sure on. Now in hindsight I'd say that the direct parent is first because it's likely the most relevant (you don't really care about PrototypeBase). But I also liked the wiki order ... 🤷‍♂️

cedar tapir Dec 13, 2023, 9:12 AM

#

I think fundamentally, starting with the most abstract and general is the regular presentation of things

topaz hill Dec 13, 2023, 9:13 AM

#

we ended up going with the current order because we wanted the intro sentence and it wants that order. Without the intro I think it's quite free floating to just have it in the page randomly (since it's not at the top like on the wiki). But you don't want the intro 🤔

cedar tapir Dec 13, 2023, 9:14 AM

#

I'd consider an intro acceptable. :thonk: I'm not sure what would go in it. Things relevant to modders, particular behavior of that entity?

#

I like the introduction to Prototype/Inserter

#

An inserter.

#

💯

topaz hill Dec 13, 2023, 9:15 AM

#

I mean the intro to the inheritance

#

"Inherits from"

#

which you say to remove :D

cedar tapir Dec 13, 2023, 9:15 AM

#

Oh oh, sorry.

#

Yeah. I don't think it needs to be there.

#

I think having the Ancestor in front just repeats that

#

If someone was like "what is this" they click it - and can see all these things are from that

#

The meaning is itself

topaz hill Dec 13, 2023, 9:19 AM

#

fun times to look at how other api docs do it. Same class, 3 different websites:

cedar tapir Dec 13, 2023, 9:20 AM

#

I've often felt game developers were in a special position, compared to a lot of other roles that always have trouble finding good solutions.

#

...such as conveying information in a way that's efficient and sensible

#

The first image is the example of the API's inheritance at the moment. It's ironic the individual elements are still left-to-right

#

The class::thing, and folder layout lol

topaz hill Dec 13, 2023, 9:26 AM

#

cedar tapir I've often felt game developers were in a special position, compared to a lot of...

as in game devs have trouble finding good solutions or other roles have trouble finding good solutions?

cedar tapir Dec 13, 2023, 9:26 AM

#

Other roles.

#

It is a tangent, but "how do we keep people engaged" has been a looooooong discussion in other topics, meanwhile, keeping someone engaged is like, goal #1 of making a game

#

And they never just... asked how game makers do it

#

One thing, stylistically speaking. The indentation for the API is slightly amiss. It's hard to suggest anything, but the Title of a table and the contents seem reasonable - but for the prototypes, there is a section separator like Inherited from EntityPrototype

#

It might feel redundant, but having one line under Properties, with the class repeated, might create a visual expectation that is consistent with the other "Inherited from" lines

#

A small visual indicator: below Properties and above FooPrototype, would uhhh "prime" someone for the layout of what's to follow: a thingPrototype and then the properties from it

#

It's a change to the visual structure a bit, but starting at the top, and then scrolling down and then the layout changing slightly in an unexpected way with the "Inherited from" space feels ever so slightly wrong

#

It might be me, but it feels like, "ok we went from Properties, indent 1, to the properties, indent 2, but... where do I put this third thing?"

topaz hill Dec 13, 2023, 9:36 AM

#

I think I might need a screenshot indicating what areas you mean, I'm getting lost in your description 😅

#

the indentation is off (haha), but do you mean a line like this? And where/how would you indent?

cedar tapir Dec 13, 2023, 9:40 AM

#

#

If there were a top text, I would have it aligned with the other "Inherited from" statements

topaz hill Dec 13, 2023, 9:42 AM

#

right. and you say that the current indentation of the "inherited from" statements is off somehow?

cedar tapir Dec 13, 2023, 9:45 AM

#

topaz hill Dec 13, 2023, 9:45 AM

#

ahhhh I see.

#

sometimes simpler styles like on the wiki is easier...

cedar tapir Dec 13, 2023, 9:46 AM

#

It's subtle, but the wiki makes it clear with the large indentation

#

I don't think the spacing of the indentation needs to be changed, in this regard. Focusing, the bit at the top somehow became significant in its absence

#

A way to describe it might be why the indentation exists, changed

#

Going from Properties to properties, but then things change with inheritance in the middle somewhere an interruption but why

topaz hill Dec 13, 2023, 9:54 AM

#

I get what you're getting at. Now Properties is the table title and the "Inherited from" are just kind of... there. Previously they were the same kind of thing with the same formatting so it was less disorienting to have the "Inherited from" in the middle

#

Now the "InserterPrototype - inserter" is at the top of the page, so I'm having trouble with coming up with a simple way to do something similar to the old formatting that still makes sense when read

cedar tapir Dec 13, 2023, 9:56 AM

#

I am confirming that I believe you have my view of it, accurate

#

To be fair, the wiki page does repeat the information three times

topaz hill Dec 13, 2023, 9:57 AM

#

The new page also says "Properties" twice :D

cedar tapir Dec 13, 2023, 9:57 AM

#

The page title, it's in the descendancy tree, and it's at the top of the properties table

#

Maybe 4 times if you want to count Prototype/Inserter — "inserter" as 2, though that does present that the way the documentation refers to the prototype and the way the game does is different - if you know to read it that way engithink

#

Ironically, the wiki page doesn't use "Properties" until it starts describing things

#

'this is stuff' and you scroll down to see "properties" "oh, I see"

#

It worked well enough, not having "Properties" at the top 🤔

topaz hill Dec 13, 2023, 10:02 AM

#

A lot of things are also convention. Like, the rails docs (what I showed above) do something like this quite often

entity.name -- => "inserter"
``` and they don't explain on the page that the comment shows the return value. But I read and understand. Monday I wanted to use this format in our lua api docs and suddenly I was wondering if I need to explain it.
And those conventions are hard to pick out for us people who have used the docs for years, because we're so used to them 😒

cedar tapir Dec 13, 2023, 10:03 AM

#

It's an understandable concern.

#

A small mention: somewhere in the docs, the landing page, the first Prototype API Docs page, somewhere.

"The point of prototypes is to define parameters for predefined behaviour."

You could even contribute it to yourself. It would be a good "first thing" to understand about prototypes / the data stage.

topaz hill Dec 13, 2023, 10:07 AM

#

topaz hill A lot of things are also convention. Like, the rails docs (what I showed above) ...

what adds to this is that this is just the format of the irb. Similar to how you execute python on the command line. We don't do that with Factorio Lua, we always use the in-game console where you need to print to see the return value.

topaz hill Dec 13, 2023, 10:08 AM

#

cedar tapir A small mention: somewhere in the docs, the landing page, the first Prototype AP...

very good point. I keep forgetting what exactly I said, but it was so good. so thanks for the reminder and the wording

cedar tapir Dec 13, 2023, 10:11 AM

#

Oh, I see what you mean, I think

#

It's like if you did an immediate type() (in that way), it would show what it is 'as if you typed it at the console at a breakpoint right there'

#

Or the actual value engithink That is a little obscure lol

topaz hill Dec 13, 2023, 10:15 AM

#

yeah. Ruby has the fun feature that almost everything has a return value - so the return value of foo = "ooo" is in fact "ooo" and the console just prints the return value

cedar tapir Dec 13, 2023, 10:16 AM

#

I can see Factorio's Lua requiring more deliberation, because there just isn't an interactive console

#

To that extent.

topaz hill Dec 13, 2023, 10:17 AM

#

yup. And when we use the console in examples you're often using game.player and then that doesnt work in actual code and ChibiOhno

cedar tapir Dec 13, 2023, 10:19 AM

#

Well, that could be made clearer, but writing commands has a pretty sharp distinction, after learning the minimum about player_index and game.players. Which is, conveniently, about the maximum to know, too

#

The only way it could be made more obvious, maybe code-wise, is having a me object or game.me, but that could be random mod-making chat

#

I think uhhh it's been a long talk about API / wiki stuff

#

I want to space out

topaz hill Dec 13, 2023, 10:21 AM

#

thank you for the feedback 👋

cedar tapir Dec 13, 2023, 10:21 AM

#

Wiki is easier to say than API 💦

#

And, uh manners, thank you for listening

topaz hill Dec 13, 2023, 10:59 AM

#

note from @sharp condor 's stream:
prototype inheritance breadcrumbs (prototypebase etc) is kinda in there with everything, maybe separate it more visually. "very compact" while pointing at that and toc and saying breadcrumbs were better in wiki
engithink

topaz hill Dec 13, 2023, 11:00 AM

#

cedar tapir I think "Inherits From" could be completely removed, and if the order were rever...

quite similar to this

sharp condor Dec 13, 2023, 1:33 PM

#

Hey! So, I've been thinking about it a bit

#

First, I'll say that with use, I've been getting more used to the new doc layout

#

That said, there's a few things I'd observe about the new API that I think warrant consideration

#

First, I think I get what I didn't like about the breadcrumbs -- they go opposite of my expected reading order

#

#

The wiki has it in the way I'd expect -- that is, the same way I read directories in a file explorer (in Windows; can't speak for other OS users)

#

It goes backwards in the API docs, and while people can adapt, that's a thing

#

Second, I think I can pin down why I find the wiki layout to be 'cleaner'

#

The separation between areas isn't done with hard borders, but rather, just layout choices

#

When I takea snippet like this, it's pretty easy to tell that the inset light-grey area beneath is being titled by Inherited from PrototypeBase, but it's a thing my eyes miss as I scan

#

another thing is that the ::'s don't line up across chunks:

#

For the longest time, I thought they were like, totally different categories of thing

#

Contrasting that with the wiki:

#

My eye follows this flawlessly. That said, I'm accustomed to tab-indentation segmenting things like this, so I am not gonna claim my experience is universal

visual sinew Dec 13, 2023, 1:45 PM

#

It geels easier to read

sharp condor Dec 13, 2023, 1:47 PM

#

Once we get down to here, there's only a few small things that trip me up

#

The boldface word Default is grabbing my attention harder than the property itself

#

#

In the wiki, the properties had a larger font size, and it was a LOT easier for my brain to just scan-and-find

#

Yes, often I navigate there by clicking on the property in the list above -- but just as often, I don't, because I've already navigated my browser there and I'm just scrolling-and-finding

#

Then ... there's this

#

The idea behind it is sound

#

But there's another few snags here to consider

#

I prefer hierarchical ordering (like from the wiki) better than alphabetical ordering.

#

This is another spot of personal preference -- but I also feel like there are a lot of objective benefits to the hierarchical ordering

#

It helps people really piece together the inheritance structure of prototypes. Like, this right here:

#

That Furnace and AssemblingMachine are just child 'classes' of CraftingMachine leaps off the page at me

#

to the point where I was able to incorporate that into my mod

#

It doesn't here ... and searching for it isn't any help either

#

And I'm not getting that from the breadcrumb trail either

#

(seemingly) random stuff is blended in here. As a list of all the prototypes, sure, they belong, because ... it's a list of them

visual sinew Dec 13, 2023, 1:58 PM

#

sharp condor another thing is that the `::`'s don't line up across chunks:

table.panel-hole.docs-table {
    table-layout: fixed;
}
td.td-modif:nth-child(1) {
    width: 60%;
}
td.td-modif:nth-child(2) {
    width: 40%;
}

sharp condor Dec 13, 2023, 2:00 PM

#

But like, I feel like if I'm building prototypes, I'm probably going to try to access stuff like MouseCursor only when I'm led there via a prototype I'm working with.

#

That doesn't mean it shouldn't be searchable, but ... perhaps there's a way to organize that into something different?

sharp condor Dec 13, 2023, 2:00 PM

#

visual sinew ```css table.panel-hole.docs-table { table-layout: fixed; } td.td-modif:nth-...

What's that? 🙂

#

But don't get rid of it entirely -- I actually think it's great to expose ALL data structures like that in a searchable fashion somehow.

visual sinew Dec 13, 2023, 2:02 PM

#

sharp condor What's that? 🙂

Some CSS style implementation details that makes :: position constant 60%, for Bilka
Just in case

sharp condor Dec 13, 2023, 2:03 PM

#

Dovetailing off of that, the properties tend to blow up the search list too, and it wasn't quite obvious to me at first what was happening. For example, this.

visual sinew Dec 13, 2023, 2:03 PM

#

sharp condor But like, I feel like if I'm building prototypes, I'm probably going to try to a...

This may become a tree but that's hard to digest for how to structure it

sharp condor Dec 13, 2023, 2:04 PM

#

I would say 99% of the time, me personally, I'm trying to get to ItemPrototype. Or something that starts with the word 'item.'

#

So, my suggestion here is twofold

#

a) Make the properties that are coming up in the list either a slightly smaller font, or perhaps a slightly darker shade of burnt orange (though this gets into accessibility problems).
b) Force-percolate to the top of the list 'classes' that start with Item, and have everything beneath be whatever they are

#

Structuring the tree is perhaps not so bad

#

Actually, I think structuring it like a tree would be super useful

#

okie, gonna stream for a bit

#

come yell at me whenever lol

topaz hill Dec 13, 2023, 2:17 PM

#

sharp condor 1) I prefer hierarchical ordering (like from the wiki) better than alphabetical ...

I suggest to click that "Inheritance Tree" link at the top of the sidebar

sharp condor Dec 13, 2023, 2:19 PM

#

Huh. I did not know that was a thing. I looked right past it

topaz hill Dec 13, 2023, 2:19 PM

#

it's new-ish, so it might not have existed yet when you were first exploring the page

topaz hill Dec 13, 2023, 2:20 PM

#

sharp condor a) Make the properties that are coming up in the list either a slightly smaller ...

I already noted "Show exact match on top" based on your AmmoItemPrototype + ItemPrototype comment. I'm not happy with the search yet and this gives us more options to look into, thank you

#

also thank you for the detailed/direct style feedback. It can be rather hard to pick out what exactly is wrong when something feels off, so this is very valuable

sharp condor Dec 13, 2023, 2:21 PM

#

Very welcome, glad I can help. 🙂

sharp condor Dec 13, 2023, 2:39 PM

#

    -- Cases:
    --   * Items can have some, or all of: 'icon', 'icons' or 'pictures'. Recipes can have 'icon', 'icons' or none of those
    --       * Pull icon data from products if we're badging a recipe with no `icon` or `icons` data. It will be one of three things:
    --           * 'result'
    --           * 'results' with 1 entry
    --           * a 'main_product'
    --       * If there's no 'icons', there's a 'icon' data; make an 'icons' entry from the 'icon' data
    --       * Only make 'pictures' out of 'icons' data if needed for belts
    --   * Pictures can be one of four structures: 
    --       * A spritesheet
    --       * A struct with a sheet = spritesheet property 
    --       * A single layers = array entry 
    --       * An array of things that have layers = array
    -- If "Only GUI" is picked, then all items and recipes gets an 'icons' with badges and items without 'pictures' have one made from 'icons' without badges
    -- If "Only Belts" is picked, icons and recipes aren't touched but every item gets 'pictures' with badges added

topaz hill Dec 13, 2023, 2:40 PM

#

<3

sharp condor Dec 13, 2023, 2:49 PM

#

-- Make and badge an item with a sprite-sheet for testing purposes
local item = {
  type = "item",
  name = "globulent",
  stack_size = 1000,
  icon = "__icon-badges__/graphics/globulent.png",
  icon_size = 64,
  pictures = {
    sheet = {
      filename = "__icon-badges__/graphics/globulent.png",
      height = 64,
      width = 64,
      variation_count = 4,
      scale = 0.25
    }
  }
}
data:extend({item})
data.raw.item["globulent"].ib_badge = "Hi"

topaz hill Dec 13, 2023, 2:50 PM

#

and now back to regularly scheduled doc website feedback :D

runic mist Dec 13, 2023, 4:07 PM

#

topaz hill I suggest to click that "Inheritance Tree" link at the top of the sidebar

I'm still missing the capability to collapse that "tree" like you can on the wiki :/

#

also maybe having the tree directly on the main prototype page like it is in the wiki would make it more visible

#

rather than being kind of hidden behind 1 small link

#

actually I just noticed, the main wiki does link to that page aswell

topaz hill Dec 13, 2023, 4:14 PM

#

problem with moving it the the main page is that it pushes down the search on mobile, since that's below the main content there

runic mist Dec 13, 2023, 4:22 PM

#

hmm that is a problem I guess..

#

could it be made as a side bar thing that you can open/close instead?

topaz hill Dec 13, 2023, 4:29 PM

#

we've considered adding an extra search at the top somewhere so we dont need to do the workaround with the sidebar on mobile.
galdoc noted that it might be neat to have the tree in the sidebar at the start and only change to the list when you start searching. not sure if I like that/how viable it is.

topaz hill Dec 13, 2023, 4:45 PM

#

hm, this somewhat reads like I'm just saying no. To be clear: Putting it on the main page was also an idea we had. it's not done currently for the given reason and because I think it's not the best entry to the prototype docs (but neither is the current state of the main page, it's missing a mention of the available global classes like runtime stage has it)

quartz gazelle Dec 13, 2023, 4:48 PM

#

topaz hill now, fun question. If you expand the layout to fill the whole page (button top r...

this should default to on

#

@hollow loom this would be a good place to share your thoughts

topaz hill Dec 13, 2023, 4:52 PM

#

quartz gazelle this should default to on

humans tend to have an easier time reading something if the column isnt super wide. that's why it's off. and that's also why, when it's on, the index page text still doesnt take the full width

quartz gazelle Dec 13, 2023, 4:52 PM

#

I have a harder time reading the table when the rows are interlaced

#

I keep wikipedia on skinny mode because it's easier to read a paragraph

#

when the descriptions are between properties and methods, it makes it harder to see anything at a glance

#

I have introduced two people to modding recently, both of which I have told to click that button and immediately went "oh that's so much better"

#

small sample size, but the point stands

topaz hill Dec 13, 2023, 4:55 PM

#

an option I can see is to get rid of the button (or change the default state) to make the tables wide, but keep the free floating text wrapping earlier

quartz gazelle Dec 13, 2023, 4:56 PM

#

perhaps

topaz hill Dec 13, 2023, 4:56 PM

#

you'd end up with something like this

quartz gazelle Dec 13, 2023, 4:56 PM

#

that's not bad actually

#

another thing I think that may have been mentioned before is that some of the pages are wiki exclusive, which I'm fine with for tutorials, but the settings stage just doesn't have any normal documentation

runic mist Dec 13, 2023, 4:59 PM

#

yeah settings stage doc is kind of hidden in a wiki tutorial and the only thing of the 3 stages that is like that

quartz gazelle Dec 13, 2023, 5:00 PM

#

I know that was a WIP thing after getting the main prototype docs finished

topaz hill Dec 13, 2023, 5:00 PM

#

yeah it's been noted before, I agree with your points. It's indeed WIP

quartz gazelle Dec 13, 2023, 5:02 PM

#

I also remember having a discussion a while ago about how to make which stage you're on more obvious (which I think one of the suggestions was changing the link colors) but I think having runtime/prototype visible at all times instead of only being at the top would help with that, and that also makes it so you can switch between them much easier if you realize you're on the wrong one

#

instead of having to scroll up to the top, especially on longer pages like LuaEntity

#

last small thing, I couldn't find where data:extend is documented, if at all

#

that's an important thing for new modders

topaz hill Dec 13, 2023, 5:06 PM

#

quartz gazelle last small thing, I couldn't find where `data:extend` is documented, if at all

yep, noted that just today. Plan right now is to have a list of available global classes (mods, data, settings) on the index page, like the runtime docs do

topaz hill Dec 13, 2023, 5:06 PM

#

quartz gazelle I also remember having a discussion a while ago about how to make which stage yo...

time to make it a sticky bar at the top, though people tend to hate those 🤔

quartz gazelle Dec 13, 2023, 5:07 PM

#

it could be above the search bar perhaps

#

instead of a sticky ribbon

topaz hill Dec 13, 2023, 5:07 PM

#

that also scrolls down though

runic mist Dec 13, 2023, 5:07 PM

#

isn't data:extend provided by the games util.lua or am I misremembering something?

quartz gazelle Dec 13, 2023, 5:07 PM

#

it's in data-loader in core

#

data_loader? dataloader? whatever it is

#

not exactly somewhere people go looking lol

quartz gazelle Dec 13, 2023, 5:13 PM

#

topaz hill that also scrolls down though

yeah, but it's not a bar over the whole width of the page at least

topaz hill Dec 13, 2023, 5:14 PM

#

if it were to not scroll, that is?

quartz gazelle Dec 13, 2023, 5:45 PM

#

yes

visual sinew Dec 13, 2023, 7:04 PM

#

@topaz hill do you have pc vs mobile usage stats?

topaz hill Dec 13, 2023, 7:05 PM

#

the docs site doesnt have analytics, so no

#

I have stats for the wiki, but that's mostly gameplay parts, not the prototype docs

visual sinew Dec 13, 2023, 7:08 PM

#

topaz hill I have stats for the wiki, but that's mostly gameplay parts, not the prototype d...

And what is stats?

#

Honestly I would expect 95+% of api hits be from pc

topaz hill Dec 13, 2023, 7:09 PM

#

topaz hill the docs site doesnt have analytics, so no

see this

hollow loom Dec 15, 2023, 10:48 PM

#

I'm honestly not sure how best to phrase this.

A lot of the documentation is rather.... dry. There's a lack of cross-linking keywords. So you get a really technical mumbo-jumbo statement about what some function does, and have to go somewhere else to search for all of the words rather than center clicking on stuff and opening a few tabs.

It's really difficult to parse what sublevel you're operating at because of how the pages are formatted as well. The inheritance of various functions/properties is.. idk... not obfuscated, but it's really unintuitive because you have huge list with definitions, the spacing isn't consistent and the section headings are tiny fragments of the overall page length. Hovering elements or some kind of "you are in this subsection" on the side would be useful.

Stuff like java documentation has lists of functions and each function has it's own page. That makes browsing for a bunch of "this sounds like it's probably pretty close to what I want" things easy. Skim through them, center click a few pages, make your selection. With the current system it's really hard to skim, and the search is kind of useless because someone new to the system doesn't know which keywords to search for, and 90% of the time you get flooded with dozens of possibilities for entirely unrelated things.

Just having a "tree" style layout of various properties and their subproperties would be useful. If that already exists, I haven't found it.

topaz hill Dec 18, 2023, 1:31 PM

#

There's a lack of cross-linking keywords So you get a really technical mumbo-jumbo statement about what some function does, and have to go somewhere else to search for all of the words rather than center clicking on stuff and opening a few tabs.
For this it would help a lot to have concrete examples/issues we can tackle, so it'd be nice if you could link what you can think of right now/what you stumble across as you use the docs. https://forums.factorio.com/viewforum.php?f=233 is made for issues like this.

For your second paragraph it's not clear to me what you're referring to. There are only two sections per page (properties, overridden properties), which is less than the wiki (mandatory properties, optional properties, ignored properties, mandatory values, differing defaults) so I'm guessing those are not the sections you mean. Could you elaborate, maybe provide screenshots pointing out the inconsistent spacing?

Factorio Forums

Documentation Improvement Requests

Place to report issues and suggest improvements to the API documentation.

#

I see the equivalent to "a bunch of functions" for the prototype stage API as picking between the different prototypes to find the one for you need, which is why we list them on https://lua-api.factorio.com/latest/prototypes.html with short descriptions of what each of them is good at. Similarly, we list the uses of types like RenderLayer so that you can easily find a prototype with a controllable render layer (a common usecase).
However, I agree that the search isn't ideal, especially because the properties are sometimes not well named. My "weapon" against it so far is to use my browser search on the prototype overview page since it has the short descriptions which provide some more (better) keywords. Or when I'm searching for something for a specific prototype, I ctrl + f that prototype page, since it will find things that aren't mentioned in the short descriptions at the top. Do you have suggestions for how to improve the search? E.g. would an optional full text (that is, property names and descriptions) search help you at all?

topaz hill Dec 18, 2023, 1:59 PM

#

Just having a "tree" style layout of various properties and their subproperties would be useful. If that already exists, I haven't found it.
We try to make examples to give a quick overview, e.g. https://lua-api.factorio.com/latest/types/Animation.html. But as you can see that's already abbreviated because it would get big if you do for example a full layers + hr_version definition. So I think a whole tree for a whole prototype would get quite huge and not useful due to information overload. E.g. CraftingMachine uses 2 Animation4Way, so it would have 8 animation definitions each with their like 30 properties in its tree. And that just for two properties of the prototype...

sharp condor Dec 18, 2023, 3:00 PM

#

Question: As I use the docs, could I throw examples your way that may help others who use them later? I'm thinking in particular of Pictures and Icons

topaz hill Dec 18, 2023, 3:09 PM

#

yep! preferably on the forums (subforum linked above). dont worry about too much formatting, just like title it "proposed example for Thing" and plop the code into the post

sharp condor Dec 18, 2023, 3:10 PM

#

Sounds good!

#

Can you pin the subforum? ❤️

#

i'm so bad at navigating the forums

topaz hill Dec 18, 2023, 3:10 PM

#

it's linked at the bottom of the doc page, behind the feedback link

sharp condor Dec 18, 2023, 3:16 PM

#

Cool, thx 🙂

topaz hill Dec 19, 2023, 4:54 PM

#

because it was a topic here: I added examples for Sprite (simple, layers, hr version, layers with hr version), SpriteVariations (array, sheet property) and AnimationVariations (array, sheet property) for the next version

topaz hill Dec 19, 2023, 6:52 PM

#

also added a note on ItemPrototype::pictures about the scale for the 64 size

topaz hill Jan 9, 2024, 11:59 AM

#

visual sinew ```css table.panel-hole.docs-table { table-layout: fixed; } td.td-modif:nth-...

Unfortunately such a simple solution doesnt work due to how the table adjusts depending on screen size (moving the description around)

#

I also recall that we had issues with overly long property names or types, for property names UtilitySprites has the worst I think and for type + property name combination the filtered prototypes on LuaGameScript are pretty bad

sharp condor Jan 9, 2024, 1:43 PM

#

EntityWithPersonalityButNotEnnuiOrUnbridledOptimism

topaz hill Jan 9, 2024, 1:54 PM

#

max_successful_attempts_per_tick_per_construction_queue_modifier_constant garlicdoggo

sharp condor Jan 9, 2024, 2:26 PM

#

wait is that for real

runic mist Jan 9, 2024, 2:34 PM

#

it is

#

https://lua-api.factorio.com/latest/prototypes/UtilitySprites.html#max_successful_attempts_per_tick_per_construction_queue_modifier_constant

topaz hill Jan 9, 2024, 7:59 PM

#

quartz gazelle last small thing, I couldn't find where `data:extend` is documented, if at all

now documented, will be released with 1.1.102

topaz hill Jan 9, 2024, 8:00 PM

#

topaz hill yep, noted that just today. Plan right now is to have a list of available global...

(this too)

runic mist Jan 9, 2024, 8:02 PM

#

so settings will be in the lua docs now?

topaz hill Jan 9, 2024, 8:02 PM

#

no, that's about the data stage access to the settings values, not the settings stage prototype creation

runic mist Jan 9, 2024, 8:03 PM

#

ah

topaz hill Jan 9, 2024, 8:03 PM

#

settings stage prototype creation docs are here: https://wiki.factorio.com/Tutorial:Mod_settings

Tutorial:Mod settings

runic mist Jan 9, 2024, 8:03 PM

#

yeah I know that they are in the wiki at the moment

topaz hill Jan 9, 2024, 8:03 PM

#

they will be moved to the doc site at some point in the future™️ but it is not high priority

#

your doc diffing thingy will have a lot of work with https://forums.factorio.com/viewtopic.php?f=234&t=110403 btw, it's a lot of changed lines

Factorio Forums

Use string unions instead of generic string

There are a number of places where things like function parameters and concept fields have a type of string, but can only be strings from a defined list. Wou…

runic mist Jan 9, 2024, 8:06 PM

#

I feared as much yeah

topaz hill Jan 9, 2024, 8:06 PM

#

ah wait not that's runtime nevermind, you dont care about that

runic mist Jan 9, 2024, 8:06 PM

#

but its not that usable anyways, would need a proper web ui or something to display changes in a more structured format

quartz gazelle Jan 9, 2024, 8:07 PM

#

I did some searching in the prototype docs but I couldn't find anything

#

that seems to be good from the start

topaz hill Jan 9, 2024, 8:07 PM

#

yeah we converted those when we did the migration from the wiki. sounds like we didnt miss anything then :D

topaz hill Jan 9, 2024, 8:12 PM

#

cedar tapir A small mention: somewhere in the docs, the landing page, the first Prototype AP...

almost forgot - also done for 1.1.102

topaz hill Jan 15, 2024, 2:01 PM

#

more updates on done things for 1.1.102:
wide mode is the new default. it has restricted paragraph width so the text wont stretch your whole widescreen monitor
better formatting for the properties (default no longer stands out as much, property name stands our more)

#

thanks for the feedback here, the larger items are also on our todo list for when we have time for them

pseudo bolt Jan 17, 2024, 5:53 AM

#

I still go to the old docs to find community edits for confusing parts of the API. Like I made some edits for turrets and attack parameters and they saved my butt months later. I don't know how to add those now

quartz gazelle Jan 17, 2024, 5:55 AM

#

you don't

#

you can suggest them in the docs improvements subforum

topaz hill Jan 17, 2024, 6:56 AM

#

To be clear, the community contributions from the wiki were also migrated to the website. But new contributions are done via the forums.

pseudo bolt Jan 19, 2024, 4:33 AM

#

It's hard to tell what track which doc suggestions actually happened in the forum. It might be a little easier if it used a bug/ticket system to clearly see "this suggestion was fixed/refused/whatever".

I remember seeing forum threads being crossed off but it's not like I got a message or something later to say my suggestion happened/was refused. Not getting a confirmation later made me not as interested in filling another one later, whether or not the suggestion was actually adopted.

But you guys seriously rock. You're more responsive than my coworkers and the docs are better than everything at my job.

quartz gazelle Jan 19, 2024, 5:00 AM

#

isn't there a resolved requests subforum?

runic mist Jan 19, 2024, 5:01 AM

#

yes

#

https://forums.factorio.com/viewforum.php?f=234

Factorio Forums

Resolved Requests

www.factorio.com

#wiki prototype docs - why do you still use them?