HugsLib

Entry point for the library. Instantiated by the game at the start of DoPlayLoad().

Handles the key presses for key bindings added by HugsLib

Ensures that the library comes after Core in the load order and displays a warning dialog otherwise.

Checks for Dev mode and bypasses the Restart message box. Holding Shift will prevent the automatic restart.

Provides an entry point for late controller setup during static constructor initialization.

Forwards ticks to the controller. Will not be saved and is never spawned.

Holds references to key binding defs used by the library.

A base for managers that save data in xml format, to be stored in the save data folder

This is added as a component to the GameObject on scene to forward events to the controller.

Represents the information stored in the About/Version.xml file. Since we cannot update the version of the library assembly, we have to store the version externally.

A shorter, invariable alternative to System.Version in the format of major.minor.patch Also known as a semantic version number. System.Version can be implicitly cast to this type. VersionShort is no longer used by HugsLib internally, and the type is retained for backwards compatibility.

Displays a list to update feature defs with basic image and formatting support. See for proper syntax.

Stores the highest displayed update news version for all mods that provide update news via . Defs are loaded from the News folder in the root mod directory.

Shows the news dialog window when there are not yet displayed news items available.

Pass true to disable filtering based on what has and has not been seen and open the dialog with all available news items. true, if there have been found news items that were not displayed before, and the dialog has been opened

Used to indicate that a type should be instantiated at the earliest moment possible. Specifically, when classes are instantiated (see .DoPlayLoad()). If is true, Harmony patching will also happen at that time.

The front-end for LogPublisher. Shows the status of the upload operation, provides controls and shows the produced URL.

Collects the game logs and loaded mods and posts the information on GitHub as a gist.

Allows adding custom buttons to the EditWindow_Log window.

Alignment side for custom widgets.

Callback to draw log window widgets in.

The log window being dawn. Window area for custom widgets. The currently selected log message, or null. Draw your widget using this to automatically align it with the others.

Adds a new drawing callback to the log window widget drawer.

The delegate called each OnGUI to draw the widget. The side of the WidgetRow this widget should be drawn into.

Adds an entry point to draw and additional debug button on the toolbar. The infix is necessary to catch the WidgetRow that the stock buttons are drawn to.

Extends the width of the immediate window the dev toolbar buttons are drawn to to accommodate an additional button

Adds a hook for the early initialization of a Game.

Forces a game restart after a language change. This is necessary to avoid creating problems for running mods caused by reloaded graphics and defs.

Adds a hook for discarding maps.

Replaces the "Mod Settings" button in the Options dialog with our own.

Adds extra buttons to the Log window.

Adds a hook to produce the WorldLoaded callback for ModBase mods.

Adds a hook to produce the MapGenerated callback for ModBase mods.

Adds a hook to produce the MapComponentsInitializing callback for ModBase mods.

Adds a hook to produce the MapLoaded callback for ModBase mods.

Restarts the game automatically, bypassing the message dialog, if changes in the mod configuration have been made and dev mode is on. Holding Shift will prevent the restart, while allowing the config changes to still be saved.

Adds a hook to produce the DefsLoaded callback for ModBase mods.

Adds an entry point during map quickstart for the quickstarter system. Will replace the standard scenario and map size if the quickstarter is enabled.

Hooks into the flow of the vanilla MonoBehavior.Update()

Hooks into the flow of the vanilla MonoBehavior.OnGUI() This allows to take advantage of automatic UI scaling and prevents GUI updates during a loading screen.

Allows to change settings related to the custom quickstart functionality. Strings are not translated, since this is a tool exclusively for modders.

Manages the custom quickstart functionality. Will trigger map loading and generation when the appropriate settings are present, and draws an additional dev toolbar button.

Wraps settings related to the Quickstart system for storage in a SettingHandle.

Utility methods for SettingHandleConvertible data objects. These are useful for packing and unpacking your custom fields into a string without bothering with manual serialization.

Deserializes an XML string into an existing object instance.

The serialized values to fill the object with The object to receive the deserialized values

Serializes an object into a compact XML string. Whitespace and namespace declarations are omitted. Make sure the object is annotated with SerializableAttribute and the fields to serialize with XmlElementAttribute.

The object to serialize

Commands start a new process on the target machine using platform specific commands and args to pass to the shell. Refer to the Microsoft documentation for dotNet 3.5 for more info on a process. https://msdn.microsoft.com/en-us/library/system.diagnostics.process(v=vs.90).aspx

A command to open a directory in the systems default file explorer. Since Unity's OpenUrl() is broken on OS X, we can use a shell to do it correctly.

A Command to open the log file in the systems default text editor.

A Command to cleanly restart RimWorld on the target machine.

The hub of the library. Instantiates classes that extend ModBase and forwards some of the more useful events to them. The assembly version of the library should reflect the current major Rimworld version, i.e.: 0.18.0.0 for B18. This gives us the ability to release updates to the library without breaking compatibility with the mods that implement it. See Core.HugsLibMod for the entry point.

The base class for all mods using HugsLib library. All classes extending ModBase will be instantiated automatically by at game initialization. Can be annotated with to initialize the mod at initialization time and have be called.

This can be used to log messages specific to your mod. It will prefix everything with your ModIdentifier.

The ModSettingsPack specific to your mod. Use this to create settings handles that represent the values of saved settings.

Override this and return false to prevent a Harmony instance from being automatically created and scanning your assembly for patches.

The reference to Harmony instance that applied the patches in your assembly.

A unique identifier used both as and . Override them separately if different identifiers are needed or no should be assigned to . Must start with a letter and contain any of [A-z, 0-9, -, _, :] (identifier must be valid as an XML tag name).

This is no longer used to identify mods since 7.0 (Rimworld 1.1). Use ModBase.ModContentPack.PackageId to that end instead.

A unique identifier to use as a key when settings are stored for this mod by . Must start with a letter and contain any of [A-z, 0-9, -, _, :] (identifier must be valid as an XML tag name). By default uses the PackageId of the implementing mod. Returning null will prevent the property from being assigned.

A readable identifier for the mod, used as a prefix by and in various error messages. Appear as "[LogIdentifier] message" when using . By default uses the non-lowercase PackageId of the implementing mod or the type name if that is not set.

The null-checked version of . Returns the type name if is null.

The content pack for the mod containing the assembly this class belongs to

Can be false if the mod was enabled at game start and then disabled in the mods menu. Always true, unless the of the declaring mod can't be identified for some unexpected reason.

Contains the AssemblyVersion and AssemblyFileVersion of the mod. Used by .

Added to avoid breaking mod compatibility during the 7.0 update. TODO: kill this during the next major update

Return the override version from the Version.xml file if specified, or the higher one between AssemblyVersion and AssemblyFileVersion

Called during HugsLib instantiation, accounting for mod load order. Load order among mods implementing is respected. and only if the implementing class is annotated with .

Called when HugsLib receives the call. Load order among mods implementing is respected. Called after the static constructors for non-HugsLib mods have executed. Is not called again on def reload

An alias for , both or either can be used, although makes for clearer code by indicating when the method is called.

Called on each tick when in Play scene

The sequential number of the tick being processed

Called each frame

Called each unity physics update

Called on each unity gui event, after UIRoot.UIRootOnGUI. Respects UI scaling and screen fading. Will not be called during loading screens. This is a good place to listen for hotkey events.

Called when GameState.Playing has been entered and the world is fully loaded in the Play scene. Will not be called during world generation and landing site selection.

Called right after Map.ConstructComponents() (before MapLoaded)

The map being initialized

Called right after a new map has been generated. This is the equivalent of MapComponent.MapGenerated().

The new map that has just finished generating

Called when the map was fully loaded

The map that has finished loading

Called after a map has been abandoned or otherwise made inaccessible. Works on player bases, encounter maps, destroyed faction bases, etc.

The map that has been discarded

Called after each scene change

The scene that has been loaded

Called after settings menu changes have been confirmed. This is called for all mods, regardless if their own settings have been modified, or not.

Called after StaticInitialize and when defs have been reloaded. This is a good place to inject defs. Get your settings handles here, so that the labels will properly update on language change. If the mod is disabled after being loaded, this method will STILL execute. Use ModIsActive to check.

There is no scenario in which defs are reloaded without the game restarting, save for a mod manually initiating a reload. When def reloading is not an issue, anything done by this method can be safely done in StaticInitialize.

Describes a single update news item. Recommended to be placed in the /News folder in the root directory of the mod. Can be loaded from the /Defs folder, but any placed in the /News folder will unload all s loaded from /Defs.

An optional unique identifier to reference the mod that adds this news item. If not set, the PackageId of the mod will be used. Must start with a letter and contain any of [A-z, 0-9, -, _, :]

Used to preserve compatibility with pre-RW1.1 HugsLib news data, such as already displayed news items and ignored news providers. Previously used to reference a BodBase.ModIdentifier which had to be loaded for the defining news def to be displayed.

Displayed in the title of the news item

Optional complete replacement for the news item title

The version number associated with the news item. Format: major.minor.patch Used to sort news items and determine which items have not been displayed yet.

For example, after an item with version 3.2.1 has been displayed, adding an item with version 3.2.0 will not cause the New Mod Features dialog to automatically open. However, both items will still appear the next time the dialog is opened. The version of the mod adding the news item is no longer required to be equal or higher for a news item to be displayed.

The text of the news item. Can contain text and images, supports Unity html markup (only recommended for highlighting). The text can contain the following formatting markers: | -> (pipe) splits the content into segments. A segment can be a paragraph or image sequence img:name1,name2 -> Displays a horizontal image sequence. Image names are file names without the extension. caption:text -> Attaches a text paragraph on the right side of the preceding image Everything else is treated as plain text and creates a paragraph.

Paragraph1|Paragraph2|img:singleImage|caption:caption\ntext|img:sequence1,sequence2|More text

When set to true (true by default), leading and trailing whitespace characters (spaces, tabs, newlines) are removed from content captions and paragraphs. This makes it easier lay out your content and not have to cram everything into one line.

Optional link to a forum post/info page for this update, or the whole mod. Displayed in the news item title.

Returns the Id of the owning mod. is used if defined, and ModContentPack.PackageId otherwise.

An options window for all configurable settings exposed by mods using the library

Injects the "Mod Settings" button into the Options dialog.

Base type for all custom SettingHandle types. Allows complex data structures to be stored in setting values by converting them to and from their string representation. See for an easy way to serialize complex types to XML.

Return false to prevent this object from serializing and being written to file.

Called when settings handles of this type load an existing value. Should deserialize and restore the state of the object using the provided string.

Called when handles of this type are being saved, and only if return true. Should serialize the state of the object into a string so it can be restored later.

A set of useful value constraints for use with SettingHandle

A group of settings values added by a mod. Each mod has their own ModSettingsPack. Loaded values are stored until they are "claimed" by their mod by requesting a handle for a setting with the same name.

Identifier of the mod that owns this pack

The name of the owning mod that will display is the Mod Settings dialog

Special display order for the mod in the Mod Settings dialog. Mods are generally ordered by name. Please leave this at Normal unless you have a good reason to change it.

Returns true if any handles retrieved from this pack have had their values changed. Resets to false after the changes are saved.

Enumerates the handles that have been registered with this pack up to this point.

Set to true to disable the collapsing of setting handles in the Mod Settings dialog.

Retrieves an existing SettingHandle from the pack, or creates a new one. Loaded settings will only display in the Mod Settings dialog after they have been claimed using this method.

The type of setting value you are creating. Unique identifier for the setting. Must be unique for this specific pack only. A display name for the setting that will show up next to it in the Mod Settings dialog. Recommended to keep this short. A description for the setting that will appear in a tooltip when the player hovers over the setting in the Mod Settings dialog. The value the setting will assume when newly created and when the player resets the setting to its default. An optional delegate that will be called when a new value is about to be assigned to the handle. Receives a string argument and must return a bool to indicate if the passed value is valid for the setting. Used only for Enum settings. Enum values are displayed in a readable format by the following method: Translate(prefix+EnumValueName)

Returns a handle that was already created. Will return null if the handle does not exist yet.

Throws an exception if the referenced handle does not match the provided type The name of the handle to retrieve

Attempts to retrieve a setting value by name. If a handle for that value has already been created, returns that handle's StringValue. Otherwise will return the unclaimed value that was loaded from the XML file. Will return null if the value does not exist.

The name of the setting the value of which should be retrieved

Returns true, if there is a setting value that can be retrieved with PeekValue. This includes already created handles and unclaimed values.

The name of the setting to check

Deletes a setting loaded from the xml file before it is claimed using GetHandle. Useful for cleaning up settings that are no longer in use.

The identifier of the setting (handle identifier)

Prompts the to save changes if any or the registered s have handles with unsaved changes

A central place for mods to store persistent settings. Individual settings are grouped by mod using ModSettingsPack

Fires when is called and changes are about to be saved. Use and to identify changed packs, and with to identify changed handles.

Fires when is called and the settings file has just been written to disk.

Enumerates the s that have been registered up to this point.

Returns true when there are handles with values that have changed since the last time settings were saved.

Retrieves the for a given mod identifier.

The unique identifier of the mod that owns the pack If not null, assigns the property of the pack. This will be displayed in the Mod Settings dialog as a header.

Saves all settings to disk and notifies all ModBase mods by calling SettingsChanged()

Removes a settings pack for a mod if it exists. Use SaveChanges to apply the change afterward.

The identifier of the mod owning the pack

An individual persistent setting owned by a mod. The extra layer of inheritance allows for type abstraction and storing SettingHandles in lists.

Unique identifier of the setting.

Name displayed in the settings menu.

Displayed as a tooltip in the settings menu.

Should return true if the passed value is valid for this setting. Optional.

The string identifier prefix used to display enum values in the settings menu (e.g. "prefix_" for "prefix_EnumValue")

Return true to make this setting visible in the menu. Optional. An invisible setting can still be reset to default using the Reset All button.

Draw a custom control for the settings menu entry. Entry name is already drawn when this is called. Optional. Return value indicates if the control changed the setting.

When true, setting will never appear. For serialized data. No longer affects value resetting, see

When true (true by default), the setting can be reset to its default value by the player. If the handle is visible, this can be done through the right-click menu, or using the "Reset all" button. Disabling this is generally not recommended, except for specific use cases (for example, content unlocked by the player).

When true, will not save this setting to the xml file. Useful in conjunction with CustomDrawer for placing buttons in the settings menu.

Specifies by how much the + and - buttons should change a numeric setting.

When CustomDrawer is used, specifies the height of the row for the handle. Leave at 0 for default height.

Affects the order in which handles appear in the settings menu. Lower comes first, default is 0.

Returns true if the of this handle has been modified after the creation of the handle or the last time its value was saved. Automatically resets to false when saves changes. Can be manually toggled when e.g. replacing null with an instance in a handle.

Marks the handle as modified and forces all settings to be saved. This is necessary for values, as changes in reference types cannot be automatically detected.

Implicitly cast handles to the Value they carry.

Called when the Value of the handle changes. Optional.

The actual value of the setting. This is converted to its string representation when settings are saved. Assigning a new value will trigger the OnValueChanged delegate.

The value the setting assumes when initially created or reset.

Retrieves the string representation of the setting or assigns a new setting value using a string. Will trigger the Validator delegate if assigned and change the Value property if the validation passes.

Returns the type of the handle Value property.

Assigns the default value to the Value property. Ignores the property.

Returns true if the handle is set to its default value.

Provides a convenient way to read, compare and print out the assembly version and file version of assemblies.

Tries to read the file assembly version in addition to the already known assembly version.

The assembly to read The full path to the assembly file, if is not set An with only AssemblyVersion set if an exception was encountered

Reads assembly version information for a mod assembly. Mod assemblies require special treatment, since they are loaded from byte arrays and their is null.

The assembly to read The content pack the assembly was loaded from See

A way to schedule single-use callbacks for an upcoming event. Useful to break the stack and ensure code is run in the main thread. Access via HugsLibController.Instance.DoLater

Schedule a callback to be executed at the start of the next tick

Schedule a callback to be executed at the start of the next frame

Schedule a callback to be executed at the start of the next OnGUI

Schedule a callback to be executed the next time a map has finished loading

The callback receives the map that has finished loading

Registers a delegate to be called in a given number of ticks.

The delegate to be called The delay in ticks before the delegate is called Optional owner of the delegate. Callback will not fire if the Thing is not spawned at call time. If true, the callback will be rescheduled after each call until manually unscheduled

Manually remove a callback to abort a delay or clear a recurring callback. Silently fails if the callback is not found.

The scheduled callback

Only for debug purposes

A classic A15-style confirm dialog with Esc and Enter key support.

A compact message dialog with a title and a custom close button label.

A title to display in the dialog A message to display in the dialog A custom label to the close button. Optional- when null, the default label will be used instead. A callback to call when the dialog is closed

A ticking scheduler for things that require a tick only every so often. Distributes tick calls uniformly over multiple frames to reduce the workload. Optimized for many tick recipients with the same tick interval.

Registers a delegate to be called every tickInterval ticks.

The delegate that will be called The interval between the calls (for example 30 to have the delegate be called 2 times a second) The Thing the delegate is attached to. The callback will be automatically unregistered if the owner is found to be despawned at call time.

Manually removes a delegate to prevent further calls.

Throws if the provided owner is not registered. Use IsRegistered() to check. The Thing the delegate was registered with

Returns true if the passed Thing is registered as the owner of a delegate.

Returns all registered tick recipients

Returns the number of calls issued across all intervals during the last tick

Returns the number of active tickers (intervals)

Tools for working with the Harmony library.

Produces a human-readable list of all methods patched by all Harmony instances and their respective patches.

Produces a human-readable list of all methods patched by a single Harmony instance and their respective patches.

A Harmony instance that can be queried for patch information.

Produces a human-readable list of Harmony patches on a given set of methods.

Produces a human-readable list of all Harmony versions present and their respective owners.

A Harmony instance that can be queried for version information.

A catch-all place for extension methods and other useful stuff

Returns true if the left or right Shift keys are currently pressed.

Returns true if the left or right Alt keys are currently pressed.

Returns true if the left or right Control keys are currently pressed. Mac command keys are supported, as well.

Returns an enumerable as a comma-separated string.

A list of elements to string together

Returns an enumerable as a string, joined by a separator string. By default null values appear as an empty string.

A list of elements to string together A string to inset between elements If true, null elements will appear as "[null]"

Returns a version as major.minor.patch formatted string.

Checks if a Thing has a designation of a given def.

The designation def to check for

Adds or removes a designation of a given def on a Thing. Fails silently if designation is already in the desired state.

The thing to designate The DesignationDef to apply or remove True to add the designation, false to remove

Checks if a cell has a designation of a given def

The map position to check The DesignationDef to detect The map to look on. When null, defaults to VisibleMap.

Adds or removes a designation of a given def on a cell. Fails silently if designation is already in the desired state.

The position to designate The DesignationDef to apply or remove True to add the designation, false to remove The map to operate on. When null, defaults to VisibleMap.

Returns true, if a MethodInfo matches the provided signature.

Note: instance methods always take their parent type as the first parameter. The method to check Expected return type of the checked method Expected parameter types of the checked method

Returns an attribute from a member, if it exists. Mods could include attributes from libraries that are not loaded, which would throw an exception, so error checking is included.

The type of the attribute to fetch The member to fetch the attribute from

Enumerates all loaded assemblies, including stock and enabled mods.

Returns true if the mod with a matching name is currently loaded in the mod configuration.

The ModMetaData.Name to match

Copies a string to the system copy buffer and displays a confirmation message.

Expands a shorthand unix user directory path with its full system path.

Adds double quotes to the start and end of a string.

Attempts to return the patch of the log file Unity is writing to.

Sends a constructed UnityWebRequest, waits for the result, and returns the data via callbacks.

Use UnityWebRequest or WWW to construct a request. Do not call Send(). Called with the response body if server replied with status 200. Called with the error message in case of a network error or if server replied with status other than 200. The expected status code in the response for the request to be considered successful How long to wait before aborting the request

Tries to find the file handle for a given mod assembly name.

This is a replacement for mod assemblies are loaded from byte arrays. The of the assembly The content pack the assembly was presumably loaded from Returns null if the file is not found

Same as but suppresses all exceptions.

Adds a hash to a manually instantiated def to avoid def collisions.

Give a short hash to a def created at runtime. Short hashes are used for proper saving of defs in compressed maps within a save file.

The type of defs your def will be saved with. For example, use typeof(ThingDef) if your def extends ThingDef.

Injects a map component into the current map if it does not already exist. Required for new MapComponents that were not active at map creation. The injection is performed at ExecuteWhenFinished to allow calling this method in MapComponent constructors.

The MapComponent that is expected to be present is the map's component list

Gets the map component of the given type from a map. Will throw an exception if a component of the requested type is not found.

The type of your MapComponent The map to get the component from

A logger that prefixes all messages with the identifier of the issuing mod.

Writes a message to the log, prefixing it with the issuing mod identifier.

The message to write Optional substitution values for the message

Same as Message(), but the console will display the message as a warning.

Same as Message(), but the console will display the message as an error. This will open the Log window in in Dev mode.

Writes a message only if Dev mode is enabled. Message is written using Tracer.Trace with the addition of the ModIdentifier as the first value.

The strings to display

Same as Trace(), but formats the message and replaces substitution variables.

Writes an error to the log to report an exception. The message will contain the name of the method that caused the exception if a location is not provided.

The exception that occurred Optional identifier of the mod that caused the exception True, if the exception should only be reported once for that specific location. Useful for errors that will trigger each frame or tick. Optional name of the location where the exception occurred. Will display as "exception during (location)"

A tool to identify the platform the game is running on.

Utility methods for displaying debug messages during development.

Writes comma-separated log messages if the game is in Dev mode. Any non-strings will be converted to strings, and null values will appear explicitly.

Messages to output

Similar to Trace, but feeds the messages through String.Format first.

The string to interpolate Interpolation arguments

Base type for utility WorldObjects repurposed to store data. See UtilityWorldObjectManager for more info.

Handles utility WorldObjects of custom types. Utility WorldObjects are a map-independent storage method for custom data. All UWOs share the same def and aren't visible on the world, but are saved and loaded with it.

Returns an existing UWO or creates a new one, adding it to the world.

Your custom type that extends UtilityWorldObject

Displays custom settings controls for mods that use the vanilla mod settings system. The dialog shows the controls for a single mod only and is opened through Dialog_ModSettings.