ARMapRenderer: Increase line width for visibility in 1.1.
[AntennaRange.git] / README.md
toadicus 1 # AntennaRange
2 A KSP mod that enforces and encourages the use of the bigger antennas.
3
4 # For Part Developers
5 ## The Fields
toadicus 6 AntennaRange extends and augments the functionality of the stock ModuleDataTransmitter through the new `ModuleLimitedDataTransmitter` class. This class uses four additional configurable fields to define the part's behavior.
toadicus 7
toadicus 8 `nominalRange` is the range, in meters, at which the part should function identically to the stock module, i.e. without any modification to the power cost or packet size. This is used along with maxPowerFactor to calculate the maximum range of the part.
9 `simpleRange` is the same as nominalRange, but is used when the mod is in "simple" mode. In general it will probably need to be a much larger number than nominalRange.
10 `maxPowerFactor` effectively sets the maximum range of the antenna by essentially capping how much the power may be "turned up" to get better range. I originally used 8 for this number, because it felt right. I've since used 4 (for my DTS) and 16 (for my Comm. 88-88). You don't want this number to be too high, or small probes will go uncontrollable a lot when transmitting.
11 `maxDataFactor` defines the maximum "speed up" bonus that comes from using antennas at less their nominal range. I originally used 4 for this number for all parts; the DTS has a higher bonus now.
toadicus 12
toadicus 13 Note that all of the fields needed for Squad's `ModuleDataTransmitter` still need to be filled out. Depending on how you're defining your parts, they might need to go in your AntennaRange patch, or they might already be defined on the base part.
toadicus 14
15 ## The Mechanic
toadicus 16 In general, the scaling functions assume the relation `D² α P/R,` where D is the total transmission distance, P is the transmission power, and R is the data rate. Data rate increases as range decreases below nominalRange: `R α nominalRange² / D²`. By default, power use increases as range increases above `nominalRange`: `P α D² / nominalRange²`. Optionally, power use may remain fixed, and data rate instead decreases as range increases above `nominalRange`: `R α nominalRange² / D²`.
toadicus 17
18 ## Patch Conventions
19 To maximize cross-compatibility, please consider the following conventions for ModuleManager patches regarding AntennaRange:
20
toadicus 21 When providing new definitions for your own parts, always specify a `:FOR[YourModHere]` pass name.
22 Whenever changing default AntennaRange definitions (e.g. if you were going to rebalance my antennas to suit your mod), please do so in the `:AFTER[AntennaRange]` pass.
23 I recommend providing all optional functionality (e.g. enabling RemoteTech vs. AntennaRange modules) in separate patches using `:NEEDS[]` blocks.
toadicus 24
25 A sample AntennaRange configuration for an all-new mod part might look like this:
26 ```
27 @PART[modPartName]:FOR[YourModName]:NEEDS[AntennaRange,!RemoteTech]
28 {
29 MODULE
30 {
31 // ### Module Definition ###
32 name = ModuleLimitedDataTransmitter
33
34 // ### Squad Definitions ###
35 // Delay between transmission packets, in seconds
36 packetInterval = 0.10
37
38 // Data capacity of nominal transmission packets, in MiT
39 packetSize = 2
40
41 // Resource cost of nominal transmission packets, in units
42 packetResourceCost = 20.0
43
44 // Resource name to be consumed by transmission
45 requiredResource = ElectricCharge
46
47 // Animation module index, 0-based, of the antenna extend/retract animation
48 DeployFxModules = 0
49
50 // ### AntennaRange Defintions ###
51 // Range, in meters, at which the antenna behaves per the "nominal" characteristics above
52 // Used with "additive" ranges.
53 nominalRange = 10000000000
54
55 // Range, in meters, at which the antenna behaves per the "nominal" characteristics above
56 // Used with "simple" ranges.
57 simpleRange = 56250000000
58
59 // The maxmimum multiplier on packetResourceCost, essentially defining the maximum power output of the
60 // transmitter. Maximum range is defined as: maxTransmitDistance = nominalRange * sqrt(maxPowerFactor)
61 maxPowerFactor = 16
62
63 // The maximum multiplier on packetSize, essentially defining the maximum data throughput of the
64 // transmitter.
65 maxDataFactor = 2
66 }
67
68 // We add this ModuleScienceContainer so that when transmission fails the antennas can try to stash the data instead of dumping it to the void.
69 MODULE
70 {
71 name = ModuleScienceContainer
72
73 dataIsCollectable = true
74 dataIsStorable = false
75
76 storageRange = 2
77 }
78 }
79 ```
80
toadicus 81 This example assumes that the base part definition does not include a `ModuleDataTransmitter` module, or any RT modules. If the base part definition includes a `ModuleDataTransmitter` module, a sample AntennaRange patch could look like this:
toadicus 82 ```
83 @PART[modPartName]:FOR[YourModName]:NEEDS[AntennaRange,!RemoteTech]
84 {
85 @MODULE[ModuleDataTransmitter]
86 {
87 @name = ModuleLimitedDataTransmitter
88 nominalRange = 10000000000
89 simpleRange = 56250000000
90 maxPowerFactor = 16
91 maxDataFactor = 2
92 }
93
94 // We add this ModuleScienceContainer so that when transmission fails the antennas can try to stash the data instead of dumping it to the void.
95 MODULE
96 {
97 name = ModuleScienceContainer
98
99 dataIsCollectable = true
100 dataIsStorable = false
101
102 storageRange = 2
103 }
104 }
105 ```
106
toadicus 107 IIRC, RemoteTech parts should not have `ModuleDataTransmitter` definitions. In that case, to facilitate RT, AR, and Stock compatibility, a suite of patches like this might be appropriate:
toadicus 108
109 ```
110 // If we don't have RemoteTech, add a stock ModuleDataTransmitter first.
111 @PART[modPartName]:NEEDS[!RemoteTech]:BEFORE[YourModName]
112 {
113 MODULE
114 {
115 // ### Module Definition ###
116 name = ModuleDataTransmitter
117
118 // ### Squad Definitions ###
119 // Delay between transmission packets, in seconds
120 packetInterval = 0.10
121
122 // Data capacity of nominal transmission packets, in MiT
123 packetSize = 2
124
125 // Resource cost of nominal transmission packets, in units
126 packetResourceCost = 20.0
127
128 // Resource name to be consumed by transmission
129 requiredResource = ElectricCharge
130
131 // Animation module index, 0-based, of the antenna extend/retract animation
132 DeployFxModules = 0
133 }
134 }
135
136 // If AntennaRange is installed, convert that to a ModuleLimitedDataTransmitter
137 @PART[modPartName]:NEEDS[AntennaRange,!RemoteTech]:FOR[YourModName]
138 {
139 @MODULE[ModuleDataTransmitter]
140 {
141 // ### Module Redefinition ###
142 @name = ModuleLimitedDataTransmitter
143
144 // ### AntennaRange Defintions ###
145 // Range, in meters, at which the antenna behaves per the "nominal" characteristics above
146 // Used with "additive" ranges.
147 nominalRange = 10000000000
148
149 // Range, in meters, at which the antenna behaves per the "nominal" characteristics above
150 // Used with "simple" ranges.
151 simpleRange = 56250000000
152
153 // The maxmimum multiplier on packetResourceCost, essentially defining the maximum power output of the
154 // transmitter. Maximum range is defined as: maxTransmitDistance = nominalRange * sqrt(maxPowerFactor)
155 maxPowerFactor = 16
156
157 // The maximum multiplier on packetSize, essentially defining the maximum data throughput of the
158 // transmitter.
159 maxDataFactor = 2
160 }
161
162 // We add this ModuleScienceContainer so that when transmission fails the antennas can try to stash the data instead of dumping it to the void.
163 MODULE
164 {
165 name = ModuleScienceContainer
166
167 dataIsCollectable = true
168 dataIsStorable = false
169
170 storageRange = 2
171 }
172 }
173
174 // If RemoteTech is installed, do their module(s) instead
175 @PART[modPartName]:NEEDS[RemoteTech]:FOR[YourModName]
176 {
177 // RemoteTech module(s) here
178 }
179 ```
180
181 ## Useful Formulas
182
183 ### Per Antenna
184 `nominalRange` is a given, and is never calculated
185 `maxPowerFactor` is a given, and is never calculated
186 `maxTransmitDistance = nominalRange * sqrt(maxPowerFactor)`
187
188 ### Per Link
189 A "link" is any connected pair of antennas.
190 `NominalLinkDistance = sqrt(nominalRange1 * nominalRange2)`
191 `MaxLinkDistance = sqrt(maxTransmitDistance1 * maxTransmitDistance2)`
192
193 Therefore, to find the `MaxLinkDistance` from two sets of `nominalRange` and `maxPowerFactor`:
194 `MaxLinkDistance = sqrt(nominalRange1 * sqrt(maxPowerFactor1) * nominalRange2 * sqrt(maxPowerFactor2))`
195
196 To find a single antenna's `nominalRange` from a desired `maxTransmitDistance` given its `maxPowerFactor`:
197 `nominalRange = maxTransmitDistance / sqrt(maxPowerFactor)`
198
199 To find a single antenna's desired maximum range given the desired maximum link distance and another set `maxTransmitDistance`:
200 `maxTransmitDistance1 = MaxLinkDistance * MaxLinkDistance / maxTransmitDistance2`
201
202 Remember that `maxPowerFactor` may differ between antennas (and does, in my lastest configs: longAntenna is 8, mediumDish is 4, commDish is 16).
203
204 Currently Kerbin's `maxPowerFactor` is hard-coded as 8.
205
206 Feel free to use this spreadsheet for balancing antennas if it's useful to you: https://goo.gl/ChsbfL
207
208 ## On Balance
209 In my configs I've balanced the three stock antennas to cover all of the stock solar system. Since you're introducing five more antennas and working with OPM, you will probably want to change the behavior of the stock parts and diversify the range to gradually cover the whole OPM system. Since you have some parts specifically designed for use in planetary subsystems, their balance when transmitting to other parts is probably more important than their balance when transmitting to Kerbin. For longer range parts designed to make the whole interplanetary leap, the inverse is probably true.
210
211 Feel free to ask questions! If anything's unclear or you just want to bounce balance ideas off of me, don't be shy. I'm always happy to help.
212