Documentation contest.

[ravenascendant]

Reply to this issue with a good readme for any MCM feature and win your name in the MCM credits.

[ravenascendant]

Multiple winners are possible if I decide to use portions of multiple entries.

[veerserif]

2024.01.24-mcm-docu.md Challenge accepted. Here's my write-up of the existing readme.txt document plus some extra information that came from my very beginner experiments with MCM. Please read this for accuracy - I write documentation, not mods. I am especially confused about prec and why it's a bad idea to call ui_mcm.get(path) in on_mcm_load(). Also, the entire "additional keybinds information" section is basically the same as the current, just tidied up.

The goal is to provide enough information and examples to allow a completely new modder to set up MCM-configurable options in their mod with a very basic options menu.

[veerserif]

cough of course I instantly noticed a bunch of typos right after I hit send 2024.01.24-mcm-docu.md but this time with 3 less typos

[ravenascendant]

TLDR it crashes the game

on_mcm_load is called as part of building the the options table. ui_mcm.get() relies on the option table. If get is called while the table is being built the results can be unpredictable ranging from not consequence to corruption of the options table or settings file.

To prevent the corruption i detect if get is called while the options table is being built and crash the game manually with a custom error message.

[ravenascendant]

prec are preconditions. the element, be it an individual option, or page of options, will not be show if the precondition evaluates to false.

[veerserif]

prec are preconditions. the element, be it an individual option, or page of options, will not be show if the precondition evaluates to false.

Oh, ok. Because in the existing documentation, prec and precondition are listed separately? I am guessing here prec means "preceding zeroes".

[prec]

• Define: (number)

• Used by: option elements: "track" allowed number of zeros in a number

  [precondition]

• Define: ( table {function, parameters} ) don't show tree options if its precondition return false

[ravenascendant]

ah crap, you are right. this is the problem with abbreviation, in my defence i inherited most of the syntax from Tronex, yeah prec in this case is precision. (edit) IGNORE THIS IT IS WRONG: If you have min at 0 and max at 2 with prec set to 0 then the slider ends up with stops at 0, 1 and 2. if you set prec to 1 it has 0.0, 0.1, 0.2 .... 1.8, 1.9, 2.0

[ravenascendant]

ok. wow. i need to not answer questions liek this before coffee

the step value pikcs the number of stops

prec relates solely to how the data is stored in the settings file.

It is entierly posible to have stops on the slider endup being discarded by not setting prec to the corect value. a step of 0.1 and a prec of 0 would do that. that would be bad. also if prec is omitted it defualts to 6 decimal places.

this field is mostly a land mine. unless ppl really need mcm to do thier rounding for them they should just omit it. TBH i should probably start deriving prec from the step.

[ravenascendant]

idk something like this maybe:

[prec]

• Define: (number)
• Used by: option elements: "track" Input value will be rounded up to have no more than this number of decimal places. Defaults to 6. Unless suning cmd to pass this value into a console command or more than 6 decimal places are needed this can be omitted. Should always be equal to or exceed the number of decimal places in step.

[ravenascendant]

I think it exists because some console commands are very particular about getting 1.0 vs 1 and since MCM can be set to call console commands directly from the option entry there needed to be a way to set the decimal places. it's almost more a feature of cmd than of the tracker.

[veerserif]

Thanks for answering my questions - I would be happy to incorporate them into the readme above, it'll probably take me some weeks since I have some IRL stuff to do. Just let me know if you have other comments to make.

EDIT: Also I'm on the Anomaly discord with the same username if you'd prefer a different platform than Github comments

[vaunakiller]

@veerserif hey its just so happened I decided to format original docs to markdown (w/o knowing about your stuff yet)

Maybe we can merge yours new and shiny doc with the stuff I formatted

1. I've addressed some issues with tables - albeit its all "old" docs
2. Also broken down some more verbose paragraphs into hopefuly, more readable, lists
3. At the bare minumum I can suggest to wrap all lua code into: ```lua -- some lua script here ``` Since it'll enable a pretty highliting. e.g.:

   function on_mcm_load()
   op = { 
        id = "modname", sh = true, gr =
           {   -- options tree goes here
               { id = "title1", type = "slide", link = "AMCM_Banner.dds", text = "ui_mcm_example_text", size = {512,50}, spacing = 20 },
               { id = "value_1", type = "input", val = 2, def = some_value_here },
           }
       }
   return op
   end

Maybe I'll look into the actual contents too, as-I-go and suggest edits (I've only started with MCM)

[veerserif]

@vaunakiller oh sick! sorry for the late reply, IRL has kept me busy. Wasn't aware that LUA highlighting worked on Github, afaik it depends on the markdown implementation so I decided to avoid it for compatibility. I am about to go back over my draft with the updated info about certain variables like prec anyway, so I could incorporate your list formatting?

[veerserif]

@ravenascendant new version of documentation, changes are listed below:

• Information about prec added including the suggestion to not to use it
• Reasoning added to explain why you shouldn't call ui_mcm.get(path) in on_mcm_load()
• Lua highlighting added to all relevant code blocks
• Minor rearrangement of sections for logical flow
• Table of Contents + internal anchors added, for internal/external quick-linking
• Rewording, typo fixes
• Summary section added to "Adding MCM Functionality" section

2024.03.20-mcm-docu.md I know markdown but I don't know how git works hence no pull request...

eta: ok apparently github does markdown anchors already so we'll see how it renders the custom anchor names. If it breaks, it should be a relatively easy fix.