-
Notifications
You must be signed in to change notification settings - Fork 37
/
Mod.cs
329 lines (299 loc) · 19.4 KB
/
Mod.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
namespace SMLHelper.V2.Examples
{
using HarmonyLib;
using SMLHelper.V2.Commands;
using SMLHelper.V2.Handlers;
using SMLHelper.V2.Interfaces;
using SMLHelper.V2.Json;
using SMLHelper.V2.Json.Attributes;
using SMLHelper.V2.Options;
using SMLHelper.V2.Options.Attributes;
using System;
using UnityEngine;
using UnityEngine.UI;
using BepInEx;
using BepInEx.Logging;
[BepInPlugin(GUID, MODNAME, VERSION)]
public class ExampleMod: BaseUnityPlugin
{
private const string
MODNAME = "SMLHelper",
AUTHOR = "The SMLHelper Dev Team",
GUID = "SMLHelperExampleMod",
VERSION = "2.15.0.1";
internal static ManualLogSource LogSource { get; private set; }
/// <summary>
/// A simple SaveDataCache implementation, intended to save the players current position to disk.
/// </summary>
[FileName("player_position")]
internal class SaveData : SaveDataCache
{
public Vector3 PlayerPosition { get; set; }
}
public void Awake()
{
LogSource = base.Logger;
/// Here, we are setting up a instance of <see cref="Config"/>, which will automatically generate an
/// options menu using Attributes. The values in this instance will be updated whenever the user changes
/// the corresponding option in the menu.
Config config = OptionsPanelHandler.Main.RegisterModOptions<Config>();
/// In a similar manner to the above, here we set up an instance of <see cref="SaveData"/>, which will
/// automatically be saved and loaded to and from disk appropriately.
/// The values in this instance will be updated automatically whenever the user switches between save slots.
SaveData saveData = SaveDataHandler.Main.RegisterSaveDataCache<SaveData>();
// Simply display the recorded player position whenever the save data is loaded
saveData.OnFinishedLoading += (object sender, JsonFileEventArgs e) =>
{
SaveData data = e.Instance as SaveData; // e.Instance is the instance of your SaveData stored as a JsonFile.
// We can use polymorphism to convert it back into a SaveData
// instance, and access its members, such as PlayerPosition.
string msg = $"loaded player position from save slot: {data.PlayerPosition}";
LogSource.LogInfo(msg);
ErrorMessage.AddMessage(msg);
};
// Update the player position before saving it
saveData.OnStartedSaving += (object sender, JsonFileEventArgs e) =>
{
SaveData data = e.Instance as SaveData;
data.PlayerPosition = Player.main.transform.position;
};
// Simply display the position we recorded to the save file whenever the save data it is saved
saveData.OnFinishedSaving += (object sender, JsonFileEventArgs e) =>
{
SaveData data = e.Instance as SaveData;
string msg = $"saved player position to save slot: {data.PlayerPosition}";
LogSource.LogInfo(msg);
ErrorMessage.AddMessage(msg);
};
/// Here we are registering a console command by use of a delegate. The delegate will respond to the "delegatecommand"
/// command from the dev console, passing values following "delegatecommand" as the correct types, provided they can be
/// parsed to that type. For example, "delegatecommand foo 3 true" would be a valid command for the
/// <see cref="MyCommand"/> delegate signature. You can also use Func or Action to define your delegate signatures
/// if you prefer, and you can also pass a reference to a method that matches this signature.
///
/// Registered commands must be unique. If another mod has already added the command, your command will be rejected.
///
/// If the user enters incorrect parameters for a command, they will be notified of the expected parameter types,
/// both on-screen and in the log.
///
/// Note that a command can have a return type, but it is not necessary. If it does return any type, it will be printed
/// both on-screen and in the log.
ConsoleCommandsHandler.Main.RegisterConsoleCommand<MyCommand>("delegatecommand", (myString, myInt, myBool) =>
{
return $"Parameters: {myString} {myInt} {myBool}";
});
/// Here we are registering all console commands defined in <see cref="ExampleMod"/>, defined by decorating them
/// with the <see cref="ConsoleCommandAttribute"/>. See <see cref="MyAttributedCommand(string, int, bool)"/> below
/// for an example.
ConsoleCommandsHandler.Main.RegisterConsoleCommands(typeof(ExampleMod));
LogSource.LogInfo("Patched successfully!");
}
private delegate string MyCommand(string myString, int myInt, bool myBool);
/// <summary>
/// <para>Here, we are using the <see cref="ConsoleCommandAttribute"/> to define a custom console command, which is
/// registered via our use of <see cref="IConsoleCommandHandler.RegisterConsoleCommands(Type)"/> above.</para>
///
/// <para>This method will respond to the "attributedcommand" command from the dev console. The command will respect the method
/// signature of the decorated method, passing values following "attributedcommand" as the correct types, as long as they can be
/// parsed to that type. For example, "attributedcommand foo 3 true" would be a valid command for this method signature.</para>
///
/// <para>The decorated method must be both <see langword="public"/> and <see langword="static"/>, or the attribute will
/// be ignored. <see cref="IConsoleCommandHandler.RegisterConsoleCommand(string, Type, string, Type[])"/> allows for
/// targeting non-<see langword="public"/> methods (must still be <see langword="static"/>), and uses a
/// similar syntax to <see cref="HarmonyPatch"/> for defining the target method.</para>
/// </summary>
/// <param name="myString"></param>
/// <param name="myInt"></param>
/// <param name="myBool"></param>
/// <returns></returns>
[ConsoleCommand("attributedcommand")]
public static string MyAttributedCommand(string myString, int myInt, bool myBool = false)
{
return $"Parameters: {myString} {myInt} {myBool}";
}
}
public enum CustomChoice { One, Two, Three }
/// <summary>
/// <para>The <see cref="MenuAttribute"/> allows us to set the title of our options menu in the "Mods" tab.</para>
///
/// <para>Optionally, we can set the <see cref="MenuAttribute.SaveOn"/> or <see cref="MenuAttribute.LoadOn"/> properties to
/// customise when the values are saved to or loaded from disk respectively. By default, the values will be saved whenever
/// they change, and loaded from disk when the game is registered to the options menu, which in this example happens on game
/// launch and is the recommended setting.</para>
///
/// <para>Both of these values allow for bitwise combinations of their options, so
/// <c>[Menu("SMLHelper Example Mod", LoadOn = MenuAttribute.LoadEvents.MenuRegistered | MenuAttribute.LoadEvents.MenuOpened)]</c>
/// is valid and will result in the values being loaded both on game start and also whenever the menu is opened.</para>
///
/// <para>We could also specify a <see cref="ConfigFileAttribute"/> here to customise the name of the config file
/// (defaults to "config") and an optional subfolder for the config file to reside in.</para>
/// </summary>
[Menu("SMLHelper Example Mod")]
public class Config : ConfigFile
{
/// <summary>
/// <para>A <see cref="ChoiceAttribute"/> is represented by a group of options where only one can be selected at a time,
/// similar in usage to a dropdown or radial button group.</para>
///
/// <para>Here, we are defining a <see cref="ChoiceAttribute"/> with the label "My index-based choice", where the underlying
/// <see cref="int"/> field represents the index in an array of choices, where the values "One", "Two" and "Three" make
/// up that array. As we are not specifiying a default value, the index will by 0 by default.</para>
///
/// <para>The <see cref="OnChangeAttribute"/> is optional and allows us to specify the name of a method in the Config class to
/// call when the value has been changed via the options menu. Note that in many cases, you won't need to specify an OnChange
/// event, as the values are automatically saved to disk for you as specified by the <see cref="MenuAttribute"/>, and are
/// updated in the instance of <see cref="Config"/> returned when registering it to the options menu.</para>
///
/// <para>Here, we are specifying the name of a method which can handle any OnChange event, for the purposes of demonstrating
/// its usage. See <see cref="MyGenericValueChangedEvent(IModOptionEventArgs)"/> for an example usage.</para>
/// </summary>
[Choice("My index-based choice", "One", "Two", "Three"), OnChange(nameof(MyGenericValueChangedEvent))]
public int ChoiceIndex;
/// <summary>
/// Here, we are defining a <see cref="ChoiceAttribute"/> which uses a <see cref="string"/> as its backing field,
/// where the value represents which option is currently selected, and are specifying "Foo" as the default.
/// </summary>
[Choice("My string-based choice", "Foo", "Bar"), OnChange(nameof(MyGenericValueChangedEvent))]
public string ChoiceValue = "Foo";
/// <summary>
/// Here, we are defining a <see cref="ChoiceAttribute"/> which uses an <see langword="enum"/>-type as its backing field,
/// and the string values for each value defined in the <see langword="enum"/> will be used to represent each option,
/// so we don't need to specify them. The options will be "One", "Two" and "Three".
/// </summary>
[Choice("My enum-based choice"), OnChange(nameof(MyGenericValueChangedEvent))]
public CustomChoice ChoiceEnum;
/// <summary>
/// <para>Here, we are again defining a <see cref="ChoiceAttribute"/> with a <see langword="enum"/>-type as its backing field,
/// however we are also specifying custom strings which will be used to represent each option in the menu.</para>
///
/// <para>An option of <see cref="CustomChoice.One"/> will be represented by the <see cref="string"/> "1",
/// <see cref="CustomChoice.Two"/> will be represented by the <see cref="string"/> "2", and so on.</para>
/// </summary>
[Choice("My customised enum-based choice", "1", "2", "3"), OnChange(nameof(MyGenericValueChangedEvent))]
public CustomChoice ChoiceCustomEnum;
/// <summary>
/// <para>A <see cref="KeybindAttribute"/> is represented in the mod options menu as a customistable keybind, where the
/// user clicks the box to set the binding, stored as a <see cref="KeyCode"/>.</para>
///
/// <para>Here, we are not specifying a default, so by default this keybind will not be set.</para>
/// </summary>
[Keybind("My keybind"), OnChange(nameof(MyGenericValueChangedEvent))]
public KeyCode KeybindKey;
/// <summary>
/// <para>A <see cref="SliderAttribute"/> is used to represent a numeric value as a slider in the options menu, with a
/// minimum and maximum value. By default, the minimum value is 0 and maximum is 100.</para>
///
/// <para>Here, we are setting an initial value of 25 for the slider. We are also setting the
/// <see cref="SliderAttribute.DefaultValue"/> property so that this default can be represented by a notch in the slider.
/// </para>
/// </summary>
[Slider("My slider", 0, 50, DefaultValue = 25), OnChange(nameof(MyGenericValueChangedEvent))]
public int SliderValue = 25;
/// <summary>
/// <para>Here, we are defining a <see cref="SliderAttribute"/> with a step of 10, meaning that the value will only
/// increment/decrement by 10, resulting in possible values of 0, 10, 20, 30, and so on up to 100.</para>
///
/// <para>By default, an <see cref="int"/> has a step of 1, and a <see cref="float"/> or <see cref="double"/>
/// has a step of 0.05.</para>
/// </summary>
[Slider("My stepped slider", Step = 10), OnChange(nameof(MyGenericValueChangedEvent))]
public int SteppedSliderValue;
/// <summary>
/// Here, we are defining a <see cref="SliderAttribute"/> with a format string which defines how the numeric value
/// is displayed.
/// See <see href="https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings"/> for more
/// info on numeric format strings.
/// </summary>
[Slider("My float-based slider", Format = "{0:F2}"), OnChange(nameof(MyGenericValueChangedEvent))]
public float FloatSliderValue;
/// <summary>
/// <para>A <see cref="ToggleAttribute"/> is used to represent a checkbox in the options menu
/// and is backed by a <see cref="bool"/>.</para>
///
/// <para>Note that here we are defining two <see cref="OnChangeAttribute"/>s which correspond to different methods
/// in the class. They will both be fired when the value changes, but one of them is specific to this value only. See
/// <see cref="MyCheckboxToggleEvent(ToggleChangedEventArgs)"/> for an example usage.</para>
/// </summary>
[Toggle("My checkbox"), OnChange(nameof(MyCheckboxToggleEvent)), OnChange(nameof(MyGenericValueChangedEvent))]
public bool ToggleValue;
/// <summary>
/// <para>A <see cref="ButtonAttribute"/> is used to represent a button in the options menu, and is different to the other
/// attributes above in that it is backed by a public method rather than a field or property, and the method that is
/// decorated with the <see cref="ButtonAttribute"/> will be called when the corresponding button is clicked, allowing you
/// to perform some custom action on demand from the options menu.</para>
///
/// <para>Here, we are also defining an <see cref="OnGameObjectCreatedAttribute"/> to demonstrate its usage. In most cases,
/// this attribute will not be needed, but in some cases if you would like to perform some special action with the
/// <see cref="GameObject"/> it can be useful. See <see cref="MyGameObjectCreatedEvent(GameObjectCreatedEventArgs)"/> for an
/// example usage.</para>
/// </summary>
/// <param name="e">The <see cref="ButtonClickedEventArgs"/> passed from the button click event, containing the id of the
/// button as a string. It is worth mentioning that it is not necessary to define the <see cref="ButtonClickedEventArgs"/>
/// if you don't need it.</param>
[Button("My button"), OnGameObjectCreated(nameof(MyGameObjectCreatedEvent))]
public void MyButtonClickEvent(ButtonClickedEventArgs e)
{
ExampleMod.LogSource.LogInfo("Button was clicked!");
ExampleMod.LogSource.LogInfo($"{e.Id}");
}
/// <summary>
/// This method will be called whenever a value with an <see cref="OnChangeAttribute"/> referencing it by name is changed.
/// In this example, only the field <see cref="ToggleValue"/> references it, so it will only be called whenever this value
/// is changed by the user via the options menu.
/// </summary>
/// <param name="e">The <see cref="ToggleChangedEventArgs"/> passed from the onchange event, containing the id of the field
/// as a string as well as the new value. As with the other events in this example, it is not necessary to define the
/// parameter if you do not need the data it contains.</param>
private void MyCheckboxToggleEvent(ToggleChangedEventArgs e)
{
ExampleMod.LogSource.LogInfo("Checkbox value was changed!");
ExampleMod.LogSource.LogInfo($"{e.Value}");
}
/// <summary>
/// This method will be called whenever a value with an <see cref="OnChangeAttribute"/> referencing it by name is changed.
/// In this example, every field above references it, so it will be called whenever any value in this class is changed by the
/// user via the options menu.
/// </summary>
/// <param name="e"><para>The data from the onchange event, passed as the interface <see cref="IModOptionEventArgs"/>.</para>
///
/// <para>As this particular method is being used as an onchange event for various field types, the usage of the
/// <see cref="IModOptionEventArgs"/> interface here enables coercion to its original data type for correct handling, as
/// demonstrated by the <see langword="switch"/> statement below.</para>
///
/// <para>As with the other events in this example, it is not necessary to define the parameter if you do not need the data
/// it contains.</para></param>
private void MyGenericValueChangedEvent(IModOptionEventArgs e)
{
ExampleMod.LogSource.LogInfo("Generic value changed!");
ExampleMod.LogSource.LogInfo($"{e.Id}: {e.GetType()}");
switch (e)
{
case KeybindChangedEventArgs keybindChangedEventArgs:
ExampleMod.LogSource.LogInfo(keybindChangedEventArgs.KeyName);
break;
case ChoiceChangedEventArgs choiceChangedEventArgs:
ExampleMod.LogSource.LogInfo($"{choiceChangedEventArgs.Index}: {choiceChangedEventArgs.Value}");
break;
case SliderChangedEventArgs sliderChangedEventArgs:
ExampleMod.LogSource.LogInfo(sliderChangedEventArgs.Value.ToString());
break;
case ToggleChangedEventArgs toggleChangedEventArgs:
ExampleMod.LogSource.LogInfo(toggleChangedEventArgs.Value.ToString());
break;
}
}
/// <summary>
/// The method will be called whenever the <see cref="GameObject"/> for a member with a
/// <see cref="OnGameObjectCreatedAttribute"/> referencing it by name is created. In this example, only the
/// <see cref="MyButtonClickEvent(ButtonClickedEventArgs)"/> button is referencing it, so it will only be called whenever
/// this button is created.
/// </summary>
/// <param name="e">The <see cref="GameObjectCreatedEventArgs"/> passed from the event, containing the id of the field
/// as a string as well as the newly created <see cref="GameObject"/>.</param>
private void MyGameObjectCreatedEvent(GameObjectCreatedEventArgs e)
{
ExampleMod.LogSource.LogInfo("GameObject was created");
ExampleMod.LogSource.LogInfo($"{e.Id}: {e.GameObject}");
}
}
}