Editing Logistic Scaling

For balance reasons, Fallen London will sometimes implement ''diminishing returns'' on a gameplay mechanic. The mathematical function used for this purpose is the '''[https://en.wikipedia.org/wiki/Logistic_function Logistic function]'''.

==Effect on Gameplay==
The Logistic function is a type of [https://en.wikipedia.org/wiki/Sigmoid_function Sigmoid function] (sometimes called an "S-Curve"). As the ''input'' grows larger and larger, the ''output'' approaches a fixed value (called an asymptote). Increasing the input will continue to increase the output, but the output will never exceed the asymptote.

When used in gameplay, this means that the value of a Quality or Attribute can increase without bound, but the ''effect'' of that Quality will stay within a fixed range. This prevents gamebreaking issues which can be caused by runaway scaling, usually in the form of echo grinds, but also in the form of diminishing penalties. In the long term, this will allows Fallen London more freedom to add scaling effects for qualities which are unbounded, and to add itemization for attributes which provide scaling rewards.

==Mechanics==
The basic form for the Logistic function is given below:

<math>f(x) = \frac{1}{1+e^{-x}}</math>

The output of this function always increases as the input increase, but it also always stays between the values 0 and 1. {TODO: Add an SVG. Wikipedia has some in the public domain.} The halfway point at ''x'' = 0 is called the "inflection point." Before the inflection point, scaling is super-linear, but after the inflection point it is sub-linear. The output never actually reaches the asymptote of 1, but it gets extremely close by ''x'' = 6, and higher values of ''x'' produce almost negligible effects. Note that the function is symmetric around its inflection point. {TODO: Ideally another SVG that labels the inflection point with an arrow.}


The Logistic function can also be expressed as a shifted, scaled version of ''tanh'', one of the Hyerbolic Trigonometric functions. For consistency, this article uses the Logistic function, even though a handful of individual cases are simpler to express with ''tanh''. 

===Use in Practice===
The more advanced form of the Logistic function has additional parameters to adjust the scaling of the input and output:

<math>f(x) = C + \frac{R}{1+e^{-k(x-I)}}</math>

;''C'':The '''offset''', initial value, or left asymptote. The Logistic function approaches this values as its input ''decreases'' (towards negative infinity). The initial value of the basic form is 0.
;''R'':The size of the '''range''' of outputs. For the basic Logistic function, the output ranges from 0 to 1, so ''R = 1''. If the offset bound is 0, then the range is the same as the upper bound. If the range is negative, then the function scales down rather than up.
;''I'':The '''inflection''' point or '''midpoint''', i.e. the value of ''x'' where the output is exactly in the middle of its range. For the basic form, this is 0.
;''k'':The '''scaling factor''' that determines how quickly the diminishing returns kick in. Large values of ''k'' will cause the function to flip quickly from the lower bound to the upper bound. The scaling factor is unitless and has no straightforward physical interpretation; exact values mare determined experimentally.

===Example===
An example is the {{IL|Mired in Mail}} quality. As you read letters which increase your stats, you increase your Mired in Mail quality. As your Mired in Mail quality increases, the stat gain from each letter falls off. The stat gain starts at 70 CP per letter, eventually dropping all the way to 14. The Logistic function caps the penalty, so that players will continue to receive some benefit from the letters. 

The observed CP gain produced at different values of Mired in Mail is as follows:

{{SCurveTable
|Condition = Mired in Mail |Use Condition = no |Effect = CP Gain
|xmin = 1 |xmax = 10
|y_offset=70 |height=-56 |midpoint=7 |k=2
|Round=yes |compact=yes |lowcap=yes
}}

This has a lower bound '''''C''''' of '''14''', and a range '''''R''''' of 70 - 14= '''56'''. The halfway point of this range is 42, reached at ''x'' = '''7'''. The scaling factor '''''k''''' must be negative, because CP decreases rather than increasing, but the exact value of '''-2''' is determined through trial-and-error.

For comparison, the exact (unrounded) outputs of the Logistic function are shown below. Note the symmetry around the midpoint, which is often useful for determining the exact values of the parameters. Note also that Mired in Mail values from 1 to 4 produce a penalty so small that it is rounded away. In gameplay terms, Mired in Mail below 4 produces no penalty, an effect which comes "for free" with the Logistic function rather than being special-cased.

{{SCurveTable
|Condition = Mired in Mail |Use Condition = no |Effect = CP Gain
|xmin = 1 |xmax = 10
|y_offset=70 |height=-56 |midpoint=7 |k=2
|Round=no
}}

==Known Uses==
This is an incomplete listing of pages that are known to use Logistic Scaling. This may grow over time.

* Several options in the [[University Laboratory (Place)]] produce research which scales logistically with several advanced stats. The most notable of these is using {{IL|Artisan of the Red Science}} to research an {{IL|Impossible Theorem}}.
* Most (all?) options under [[Read incoming mail]] that produce stat gains scale logistically with {{IL|Mired in Mail}}.
* At the Chessboard in Parabola, the final moves to [[Choose a queen mate]] or [[Choose an epaulette mate]] produce {{IL|Well-Placed Pawn}} which scales ''linearly'' with {{IL|Position on the Board: Distance ahead}}, but ''logistically'' with {{IL|A Player of Chess}}.

===Suspected Uses===
* In Helicon House, the {{IL|Casing...}} gains from [[Keep a close eye on everyone present]] decrease with {{IL|Time Remaining at Helicon House}}. While the use of the Logistic function is overkill, it seems to work.
* The effect of {{IL|Supporting the Liberationist Tracklayers}} on the difficulty of certain actions is currently unknown, but could be logistic.

==Calculator==
A calculator for producing tables of effects based on parameters. The default values create the Mired in Mail table shown above.

<pre class="jcConfig">
 template = SCurveTable
 form = Scaling
 result = ScalingResult
 param = y_offset|Lower Result Bound (C)|70|int|-500-500
 param = height|Result Range (R)|-56|int|-500-500
 param = midpoint|Inflection Point (I)|7|int|-500-500
 param = k|Scale Factor (k)|2|float|0-100
 param = xmin|Table starts at|1|int|0-350
 param = xmax|Table ends at|10|int|0-1000
 param = Round|Round results?|yes|toggleswitch|yes,no
 param = Condition|Input Quality|Mired in Mail|article
 param = Effect|Output Quality|Watchful CP Gain|string
 param = Use Condition||no|hidden
</pre>

<div id="Scaling"><span style="font-weight: bold;">Calculator loading...</span></div>

<div id="ScalingResult"> </div>

==Determining Parameters==
Finding the correct parameters for a Logistic function given a set of known data is mostly a combination of intuition and trial-and-error, especially considering the rounding involved. If you can reasonably narrow down the likely ranges of parameters, the trial-and-error portion can be automated with the community-built [https://mzs42-personal.gitlab.io/fallen-london-tools/scurve-fitter/ S-Curve Finder].

===Intuition===
While narrowing down the range of parameters from infinite to tractable can seem daunting, there are a few hints and rules of thumb you can use for each:

;'''Range/Height''': If you already know the minimum and maximum outputs, you can simply subtract to find the range. If you know the minimum ''or'' maximum output and the midpoint, you can subtract and double. If you don't know either extreme but have a good guess of the midpoint, doubling the output near the midpoint is a good starting point. Remember that this number is ''negative'' if the output decreases as the input increases.
;'''Midpoint/inflection point''': If you don't yet have enough data to determine the midpoint from the height, two other important properties of an S-curve can help narrow down potential midpoints. First, the output changes most quickly near the midpoint and most slowly far away from the midpoint.  Second, the curve is symmetric around the midpoint. If you know three equidistant inputs—e.g. 10, 12, and 14—that give equidistant outputs, the middle of those three points is a good guess for the curve's midpoint. In Fallen London, the midpoint will most likely be a multiple of 1/2.
;'''Y Offset''': This is simply the output approached on the left side of the curve. In cases where data has not yet been collected for low inputs, simple game design principles can be quite suggestive. For example, it's unlikely a formula for item gain will be negative at a reachable input value. An output of 0 might make sense in some cases, but utterly ridiculous in others.
;'''k/scaling factor''': This is usually the toughest component to nail down since it doesn't directly correspond to an intuitive figure. Besides the fact that larger values means faster scaling and smaller values means slower scaling, our best rule of thumb here is to remember that the game's logistic functions are created by humans. It's simply less likely that the designer would choose "weird" values like .29 or .81752 instead of something more "normal" like 1.5 or 1/3.

===S-Curve Finder===
The [https://mzs42-personal.gitlab.io/fallen-london-tools/scurve-fitter/ S-Curve Finder] is a basic tool for helping to narrow down the parameters of a particular logistic function. Given a set of known data points and ranges and increments to check for each parameter, it will iterate through every combination and output the parameter sets that fit the given data points.

A few notes on using it:

# Data points should be given one per line in the format "input output". For example:
#:1 &nbsp; 3
#:5 &nbsp; 9
#:15 &nbsp; 28
# For each parameter, it is expected that range start will be less than range end and step will be positive. If this is not the case, the finder will still work but at the time of writing, some edge cases have mildly surprising behaviour.
# The permalink automatically updates as you edit the data and parameters to make it easy to link to particular results. The Reset button will take you back to the default state of the page, not to the version you were permalinked to. 

[[Category:Game Mechanics]]