From 728f8d7ffe90c4aded9000c7629ef062c7195a9d Mon Sep 17 00:00:00 2001 From: Ben C Date: Tue, 18 Oct 2022 08:56:24 -0400 Subject: [PATCH] Made generic API methods --- NewHorizons/INewHorizons.cs | 12 +- NewHorizons/NewHorizonsApi.cs | 19 +++ docs/content/pages/tutorials/api.md | 166 ++++++++++++---------- docs/content/pages/tutorials/extending.md | 10 +- 4 files changed, 123 insertions(+), 84 deletions(-) diff --git a/NewHorizons/INewHorizons.cs b/NewHorizons/INewHorizons.cs index 8f132ee7..14093b0d 100644 --- a/NewHorizons/INewHorizons.cs +++ b/NewHorizons/INewHorizons.cs @@ -54,11 +54,21 @@ namespace NewHorizons /// object QueryBody(Type outType, string bodyName, string path); + /// + /// Uses JSONPath to query a body + /// + T QueryBody(string bodyName, string path); + /// - /// Uses JSONPath to query a system + /// Uses JSONPath to query the current star system /// object QuerySystem(Type outType, string path); + /// + /// Uses JSONPath to query the current star system + /// + T QuerySystem(string path); + /// /// Allows you to overwrite the default system. This is where the player is respawned after dying. /// diff --git a/NewHorizons/NewHorizonsApi.cs b/NewHorizons/NewHorizonsApi.cs index a4da089f..86570294 100644 --- a/NewHorizons/NewHorizonsApi.cs +++ b/NewHorizons/NewHorizonsApi.cs @@ -129,6 +129,16 @@ namespace NewHorizons : QueryJson(outType, Path.Combine(planet.Mod.ModHelper.Manifest.ModFolderPath, planet.RelativePath), jsonPath); } + public T QueryBody(string bodyName, string jsonPath) + { + var data = QueryBody(typeof(T), bodyName, jsonPath); + if (data is T result) { + return result; + } else { + return default(T); + } + } + public object QuerySystem(Type outType, string jsonPath) { var system = Main.SystemDict[Main.Instance.CurrentStarSystem]; @@ -137,6 +147,15 @@ namespace NewHorizons : QueryJson(outType, Path.Combine(system.Mod.ModHelper.Manifest.ModFolderPath, system.RelativePath), jsonPath); } + public T QuerySystem(string jsonPath) { + var data = QuerySystem(typeof(T), jsonPath); + if (data is T result) { + return result; + } else { + return default(T); + } + } + public GameObject SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, float scale, bool alignWithNormal) { diff --git a/docs/content/pages/tutorials/api.md b/docs/content/pages/tutorials/api.md index 2afd6ffe..ee84cab3 100644 --- a/docs/content/pages/tutorials/api.md +++ b/docs/content/pages/tutorials/api.md @@ -9,99 +9,109 @@ First create the following interface in your mod: ```cs public interface INewHorizons - { - [Obsolete("Create(Dictionary config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")] - void Create(Dictionary config); +{ + [Obsolete("Create(Dictionary config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")] + void Create(Dictionary config); - [Obsolete("Create(Dictionary config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")] - void Create(Dictionary config, IModBehaviour mod); + [Obsolete("Create(Dictionary config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")] + void Create(Dictionary config, IModBehaviour mod); - /// - /// Will load all configs in the regular folders (planets, systems, translations, etc) for this mod. - /// The NH addon config template is just a single call to this API method. - /// - void LoadConfigs(IModBehaviour mod); + /// + /// Will load all configs in the regular folders (planets, systems, translations, etc) for this mod. + /// The NH addon config template is just a single call to this API method. + /// + void LoadConfigs(IModBehaviour mod); - /// - /// Retrieve the root GameObject of a custom planet made by creating configs. - /// Will only work if the planet has been created (see GetStarSystemLoadedEvent) - /// - GameObject GetPlanet(string name); + /// + /// Retrieve the root GameObject of a custom planet made by creating configs. + /// Will only work if the planet has been created (see GetStarSystemLoadedEvent) + /// + GameObject GetPlanet(string name); - /// - /// The name of the current star system loaded. - /// - string GetCurrentStarSystem(); + /// + /// The name of the current star system loaded. + /// + string GetCurrentStarSystem(); - /// - /// An event invoked when the player begins loading the new star system, before the scene starts to load. - /// Gives the name of the star system being switched to. - /// - UnityEvent GetChangeStarSystemEvent(); + /// + /// An event invoked when the player begins loading the new star system, before the scene starts to load. + /// Gives the name of the star system being switched to. + /// + UnityEvent GetChangeStarSystemEvent(); - /// - /// An event invoked when NH has finished generating all planets for a new star system. - /// Gives the name of the star system that was just loaded. - /// - UnityEvent GetStarSystemLoadedEvent(); + /// + /// An event invoked when NH has finished generating all planets for a new star system. + /// Gives the name of the star system that was just loaded. + /// + UnityEvent GetStarSystemLoadedEvent(); - /// - /// An event invoked when NH has finished a planet for a star system. - /// Gives the name of the planet that was just loaded. - /// - UnityEvent GetBodyLoadedEvent(); + /// + /// An event invoked when NH has finished a planet for a star system. + /// Gives the name of the planet that was just loaded. + /// + UnityEvent GetBodyLoadedEvent(); - /// - /// Uses JSONPath to query a body - /// - object QueryBody(Type outType, string bodyName, string path); + /// + /// Uses JSONPath to query a body + /// + object QueryBody(Type outType, string bodyName, string path); - /// - /// Uses JSONPath to query a system - /// - object QuerySystem(Type outType, string path); + /// + /// Uses JSONPath to query a body + /// + T QueryBody(string bodyName, string path); - /// - /// Allows you to overwrite the default system. This is where the player is respawned after dying. - /// - bool SetDefaultSystem(string name); + /// + /// Uses JSONPath to query the current star system + /// + object QuerySystem(Type outType, string path); - /// - /// Allows you to instantly begin a warp to a new star system. - /// Will return false if that system does not exist (cannot be warped to). - /// - bool ChangeCurrentStarSystem(string name); + /// + /// Uses JSONPath to query the current star system + /// + T QuerySystem(string path); - /// - /// Returns the uniqueIDs of each installed NH addon. - /// - string[] GetInstalledAddons(); + /// + /// Allows you to overwrite the default system. This is where the player is respawned after dying. + /// + bool SetDefaultSystem(string name); - /// - /// Allows you to spawn a copy of a prop by specifying its path. - /// This is the same as using Props->details in a config, but also returns the spawned gameObject to you. - /// - GameObject SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, - float scale, bool alignWithNormal); + /// + /// Allows you to instantly begin a warp to a new star system. + /// Will return false if that system does not exist (cannot be warped to). + /// + bool ChangeCurrentStarSystem(string name); - /// - /// Allows you to spawn an AudioSignal on a planet. - /// This is the same as using Props->signals in a config, but also returns the spawned AudioSignal to you. - /// This method will not set its position. You will have to do that with the returned object. - /// - AudioSignal SpawnSignal(IModBehaviour mod, GameObject root, string audio, string name, string frequency, - float sourceRadius = 1f, float detectionRadius = 20f, float identificationRadius = 10f, bool insideCloak = false, - bool onlyAudibleToScope = true, string reveals = ""); + /// + /// Returns the uniqueIDs of each installed NH addon. + /// + string[] GetInstalledAddons(); - /// - /// Allows you to spawn character dialogue on a planet. Also returns the RemoteDialogueTrigger if remoteTriggerRadius is specified. - /// This is the same as using Props->dialogue in a config, but also returns the spawned game objects to you. - /// This method will not set the position of the dialogue or remote trigger. You will have to do that with the returned objects. - /// - (CharacterDialogueTree, RemoteDialogueTrigger) SpawnDialogue(IModBehaviour mod, GameObject root, string xmlFile, float radius = 1f, - float range = 1f, string blockAfterPersistentCondition = null, float lookAtRadius = 1f, string pathToAnimController = null, - float remoteTriggerRadius = 0f); - } + /// + /// Allows you to spawn a copy of a prop by specifying its path. + /// This is the same as using Props->details in a config, but also returns the spawned gameObject to you. + /// + GameObject SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, + float scale, bool alignWithNormal); + + /// + /// Allows you to spawn an AudioSignal on a planet. + /// This is the same as using Props->signals in a config, but also returns the spawned AudioSignal to you. + /// This method will not set its position. You will have to do that with the returned object. + /// + AudioSignal SpawnSignal(IModBehaviour mod, GameObject root, string audio, string name, string frequency, + float sourceRadius = 1f, float detectionRadius = 20f, float identificationRadius = 10f, bool insideCloak = false, + bool onlyAudibleToScope = true, string reveals = ""); + + /// + /// Allows you to spawn character dialogue on a planet. Also returns the RemoteDialogueTrigger if remoteTriggerRadius is specified. + /// This is the same as using Props->dialogue in a config, but also returns the spawned game objects to you. + /// This method will not set the position of the dialogue or remote trigger. You will have to do that with the returned objects. + /// + (CharacterDialogueTree, RemoteDialogueTrigger) SpawnDialogue(IModBehaviour mod, GameObject root, string xmlFile, float radius = 1f, + float range = 1f, string blockAfterPersistentCondition = null, float lookAtRadius = 1f, string pathToAnimController = null, + float remoteTriggerRadius = 0f); +} ``` In your main `ModBehaviour` class you can get the NewHorizons API like so: diff --git a/docs/content/pages/tutorials/extending.md b/docs/content/pages/tutorials/extending.md index 754140d9..2aa31fb1 100644 --- a/docs/content/pages/tutorials/extending.md +++ b/docs/content/pages/tutorials/extending.md @@ -52,9 +52,9 @@ Then, use the `QueryBody` method: var api = ModHelper.Interactions.TryGetModApi("xen.NewHorizons"); api.GetBodyLoadedEvent().AddListener((name) => { ModHelper.Console.WriteLine($"Body: {name} Loaded!"); - var potentialData = api.QueryBody(typeof(MyCoolExtensionData), "$.extras.myCoolExtensionData", name); - // Makes sure the module is valid and not null - if (potentialData is MyCoolExtensionData data) { + var data = api.QueryBody("$.extras.myCoolExtensionData", name); + // Makes sure the module is not null + if (data != null) { ModHelper.Console.WriteLine($"myCoolExtensionProperty for {name} is {data.myCoolExtensionProperty}!"); } }); @@ -69,6 +69,6 @@ Extending systems is the exact same as extending planets, except you use the `Qu You can also use the `QueryBody` method to get values of the config outside your extension object ```csharp -var primaryBody = api.QueryBody(typeof(string), "Wetrock", "$.Orbit.primaryBody"); - ModHelper.Console.WriteLine($"Primary of {bodyName} is {primaryBody ?? "NULL"}!"); +var primaryBody = api.QueryBody("Wetrock", "$.Orbit.primaryBody"); +ModHelper.Console.WriteLine($"Primary of {bodyName} is {primaryBody ?? "NULL"}!"); ```