Gittes-archive/new-horizons
2
0
Fork 0
mirror of https://github.com/Outer-Wilds-New-Horizons/new-horizons.git synced 2025-12-11 20:15:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into dev

Browse Source
This commit is contained in:
xen-42 2025-04-25 12:15:01 -04:00
commit 8aa01c223d
1 changed files with 240 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
docs/src/content/docs/reference/api.md
View File

@ -10,14 +10,28 @@ Put this in a C# file somewhere in your mod:
<!-- Auto update this would be cool -->
```cs
using OWML.Common;
using System;
using System.Collections.Generic;
using System.Xml.Linq;
using UnityEngine;
using UnityEngine.Events;
namespace NewHorizons
{
public interface INewHorizons
{
#region Obsolete
[Obsolete("Create(Dictionary<string, object> config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")]
void Create(Dictionary<string, object> config);
[Obsolete("Create(Dictionary<string, object> config) is deprecated, please use LoadConfigs(IModBehaviour mod) instead")]
void Create(Dictionary<string, object> config, IModBehaviour mod);
[Obsolete("SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, float scale, bool alignRadial) is deprecated, please use SpawnObject(IModBehaviour mod, GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, float scale, bool alignRadial) instead")]
GameObject SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles, float scale, bool alignWithNormal);
#endregion
/// <summary>
/// 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.
@ -30,11 +44,30 @@ public interface INewHorizons
/// </summary>
GameObject GetPlanet(string name);
/// <summary>
/// Returns the uniqueIDs of each installed NH addon.
/// </summary>
string[] GetInstalledAddons();
#region Get/set/change star system
/// <summary>
/// The name of the current star system loaded.
/// </summary>
string GetCurrentStarSystem();
/// <summary>
/// Allows you to overwrite the default system. This is where the player is respawned after dying.
/// </summary>
bool SetDefaultSystem(string name);
/// <summary>
/// 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).
/// </summary>
bool ChangeCurrentStarSystem(string name);
#endregion
#region events
/// <summary>
/// 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.
@ -53,6 +86,19 @@ public interface INewHorizons
/// </summary>
UnityEvent<string> GetBodyLoadedEvent();
/// <summary>
/// An event invoked when NH has finished building a title screen.
/// Gives the unique name of the mod the title screen builder was from and the index for when you have multiple title screens.
/// </summary>
UnityEvent<string, int> GetTitleScreenLoadedEvent();
/// <summary>
/// An event invoked when NH has finished building the title screen.
/// </summary>
UnityEvent GetAllTitleScreensLoadedEvent();
#endregion
#region Querying configs
/// <summary>
/// Uses JSONPath to query a body
/// </summary>
@ -74,26 +120,27 @@ public interface INewHorizons
T QuerySystem<T>(string path);
/// <summary>
/// Allows you to overwrite the default system. This is where the player is respawned after dying.
/// Uses JSONPath to query a title screen config
/// </summary>
bool SetDefaultSystem(string name);
object QueryTitleScreen(Type outType, IModBehaviour mod, string path);
///<summary>
/// 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).
/// Uses JSONPath to query a title screen config
/// </summary>
bool ChangeCurrentStarSystem(string name);
T QueryTitleScreen<T>(IModBehaviour mod, string path);
/// <summary>
/// Returns the uniqueIDs of each installed NH addon.
/// Register your own builder that will act on the given GameObject by reading the json string of its "extras" module
/// </summary>
string[] GetInstalledAddons();
void RegisterCustomBuilder(Action<GameObject, string> builder);
#endregion
#region Spawn props
/// <summary>
/// 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.
/// </summary>
GameObject SpawnObject(GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles,
GameObject SpawnObject(IModBehaviour mod, GameObject planet, Sector sector, string propToCopyPath, Vector3 position, Vector3 eulerAngles,
float scale, bool alignWithNormal);
/// <summary>
@ -113,6 +160,114 @@ public interface INewHorizons
(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);
#endregion
#region Load json/xml directly
/// <summary>
/// Allows creation of a planet by directly passing the json contents as a string.
/// </summary>
/// <param name="config"></param>
/// <param name="mod"></param>
void CreatePlanet(string config, IModBehaviour mod);
/// <summary>
/// Allows defining details of a star system by directly passing the json contents as a string.
/// </summary>
/// <param name="name"></param>
/// <param name="config"></param>
/// <param name="mod"></param>
void DefineStarSystem(string name, string config, IModBehaviour mod);
/// <summary>
/// Allows creation of dialogue by directly passing the xml and dialogueInfo json contents as strings.
/// Must be called at least 2 frames before entering dialogue if you're using ReuseDialogueOptionsFrom
/// </summary>
/// <param name="textAssetID">TextAsset name used for compatibility with voice mod. Just has to be a unique identifier.</param>
/// <param name="xml">The contents of the dialogue xml file as a string</param>
/// <param name="dialogueInfo">The json dialogue info as a string. See the documentation/schema for what this can contain.</param>
/// <param name="planetGO">The root planet rigidbody that this dialogue is attached to. Any paths in the dialogueInfo are relative to this body.</param>
/// <returns></returns>
(CharacterDialogueTree, RemoteDialogueTrigger) CreateDialogueFromXML(string textAssetID, string xml, string dialogueInfo, GameObject planetGO);
/// <summary>
/// Allows the creation of Nomai text by directly passing the xml and translatorTextInfo json contents as strings
/// </summary>
/// <param name="xml">The contents of the translator text file as a string</param>
/// <param name="textInfo">The json translator text info as a string. See the documentation/schema for what this can contain.</param>
/// <param name="planetGO">The root planet rigidbody that this text is attached to. Any paths in the translatorTextInfo are relative to this body.</param>
/// <returns></returns>
GameObject CreateNomaiText(string xml, string textInfo, GameObject planetGO);
/// <summary>
/// Directly add ship logs from XML. Call this method right before ShipLogManager awake.
/// </summary>
/// <param name="mod">The mod this method is being called from. This is required for loading files.</param>
/// <param name="xml">The ship log xml contents</param>
/// <param name="planetName">The planet that these ship logs correspond to in the map mode</param>
/// <param name="imageFolder">The relative path from your mod manifest.json where the ship log images are located. The filename must be the same as the fact id. Optional.</param>
/// <param name="entryPositions">A dictionary of each fact id to its 2D position in the ship log. Optional.</param>
/// <param name="curiousityColours">A dictionary of each curiousity ID to its colour and highlight colour in the ship log. Optional.</param>
void AddShipLogXML(IModBehaviour mod, XElement xml, string planetName, string imageFolder = null, Dictionary<string, Vector2> entryPositions = null, Dictionary<string, (Color colour, Color highlight)> curiousityColours = null);
#endregion
#region Translations
/// <summary>
/// Look up shiplog-related translated text for the given text key.
/// Defaults to English if no translation in the current language is available, and just the key if no English translation is available.
/// </summary>
/// <param name="text">The text key to look up.</param>
/// <returns></returns>
string GetTranslationForShipLog(string text);
/// <summary>
/// Look up dialogue-related translated text for the given text key.
/// Defaults to English if no translation in the current language is available, and just the key if no English translation is available.
/// </summary>
/// <param name="text">The text key to look up.</param>
/// <returns></returns>
string GetTranslationForDialogue(string text);
/// <summary>
/// Look up UI-related translated text for the given text key.
/// Defaults to English if no translation in the current language is available, and just the key if no English translation is available.
/// </summary>
/// <param name="text">The text key to look up.</param>
/// <returns></returns>
string GetTranslationForUI(string text);
/// <summary>
/// Look up miscellaneous translated text for the given text key.
/// Defaults to English if no translation in the current language is available, and just the key if no English translation is available.
/// </summary>
/// <param name="text">The text key to look up.</param>
/// <returns></returns>
string GetTranslationForOtherText(string text);
#endregion
/// <summary>
/// Registers a subtitle for the main menu.
/// Call this once before the main menu finishes loading
/// </summary>
/// <param name="mod"></param>
/// <param name="filePath"></param>
void AddSubtitle(IModBehaviour mod, string filePath);
/// <summary>
/// Whatever system the player is warping to next, they will spawn at the spawn point with this ID
/// Gets reset after warping. Is also overriden by entering a system-changing black hole or warp volume by their `spawnPointID`
/// </summary>
/// <param name="id"></param>
void SetNextSpawnID(string id);
/// <summary>
/// Registers a builder for the main menu.
/// Call this once before the main menu finishes loading
/// </summary>
/// <param name="mod"></param>
/// <param name="builder">Builder to run when this title screen is selected. The GameObject passed through it is the main scene object containing both the background and menu planet.</param>
/// <param name="disableNHPlanets">If set to true, NH generated planets will not show on the title screen. If false, this title screen has the same chance as other NH planet title screens to show.</param>
/// <param name="shareTitleScreen">If set to true, this custom title screen will merge with all other custom title screens with shareTitleScreen set to true. If false, NH will randomly select between this and other valid title screens that are loaded.</param>
/// <param name="persistentConditionRequired">Persistent condition required for this title screen to appear.</param>
/// <param name="factRequired">Ship log fact required for this title screen to appear.</param>
void RegisterTitleScreenBuilder(IModBehaviour mod, Action<GameObject> builder, bool disableNHPlanets = true, bool shareTitleScreen = false, string persistentConditionRequired = null, string factRequired = null);
}
}
```