Mod Update News
The library allows mods to create short update news items to displayed to the player. Each item is tied to a specific version of the mod and is displayed only once.
News items from different mods are displayed together in the "New Mod Features" dialog that appears after a game has been loaded.
News item content supports Unity rich text, has some basic formatting options and can contain images.
All available news items for loaded mods can be viewed with a button in the Mod Settings dialog.
The purpose of the update news system is to allow mods to highlight major new features that could otherwise go unnoticed by the player.
The easiest way to decide whether a recent change in your mod should be highlighted in a news item is considering the change from the perspective of the average player.
Generally, only significant additions to their favorite mods are of interest to them, and they are likely to just hit the "Close" button if they run into a blob of text.
To best capture the attention of the player, it's a good idea to trim the text content down to a bare minimum and include relevant images, if possible.
In version 7.0 (Rimworld 1.1), HugsLib added support for update news provided by mods that do not depend on HugsLib. This is achieved by placing news def XML files in the /News folder instead of the /Defs folder, which prevents the defs from being processed by the game when HugsLib is not loaded.
News items are added by creating an XML file that contains defs of the UpdateFeatureDef type.
Here's an example of a ModName/Defs/UpdateFeatureDefs/UpdateFeatures.xml file that creates news items for two different versions of a mod:
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<HugsLib.UpdateFeatureDef Abstract="true" Name="UpdateFeatureBase">
<modNameReadable>Mod Name</modNameReadable>
<modIdentifier>ModName</modIdentifier>
<linkUrl>https://ludeon.com/forums/index.php?topic=17218</linkUrl>
</HugsLib.UpdateFeatureDef>
<HugsLib.UpdateFeatureDef ParentName="UpdateFeatureBase">
<defName>ModName_1_1_0</defName>
<assemblyVersion>1.1.0</assemblyVersion>
<content>A basic news item with text content only.</content>
</HugsLib.UpdateFeatureDef>
<HugsLib.UpdateFeatureDef ParentName="UpdateFeatureBase">
<defName>ModName_1_2_0</defName>
<assemblyVersion>1.2.0</assemblyVersion>
<content>First paragraph.|img:Things/Item/Meal/Fine,Things/Item/Meal/Lavish,Things/Item/Meal/Simple|caption:This is a caption.|Another paragraph with <b>rich text</b>.</content>
</HugsLib.UpdateFeatureDef>
</Defs>When entering the game, the news dialog should look something like this.
defName: The news Defs still require unique names to work, even though they are not used by the system.
modIdentifier: Uniquely identifies news items added by your mod. Used to store the latest seen news item by the player, as well as ignored news providers. It's a good idea to never change this once chosen. If not specified, your mod's PackageId is used.
modNameReadable: The name of the mod, as it will be displayed in the news dialog.
linkUrl: An optional link to your mod's forum or workshop page.
assemblyVersion: A version number to associate the news item with. News items are sorted based on their version number, and only a higher unread news items version will cause the news dialog to open.
Since version 7.0, HugsLib no longer requires the version of your mod's dll file to be equal or greater to a news item's assemblyVersion for it to be displayed.
content: The text of your news item. Can contain additional formatting markers (see below). When adding rich text tags, encode tags using HTML Entities or enclose the whole text in a CDATA section.
trimWhitespace: Defaults to true. When enabled, whitespace (spaces, newlines, tabs) are removed from the beginning and end of content sections. This allows to arrange the content in a more readable fashion in the XML file.
targetAudience: Specifies if the news item should appear to first-time players of your mod. Possible values: ReturningPlayers (default), NewPlayers, AllPlayers.
You might want to change this if one of your items is a tutorial fo new players. Otherwise, it is best to leave the default value and not show past update news to first-timers- they generally don't care and will pick up on major features as they play. The hidden items are still available to all players when accessed manually via the Mod Settings button.
Adding formatting markers to news item text allows to insert images and add captions for them. The system is fairly rudimentary, but in conjunction with rich text should be all that is needed to get the point across to the player.
The pipe is the delimiter that starts a new section- a paragraph, a sequence of images or an image caption.
Paragraph example: One|Two|Three
The pipe character immediately followed by img: and an image resource name will insert an image into the text.
Images should be placed under the /News folder to ensure that they are not loaded by the game on startup- this saves both loading time and memory. The file name should be specified without the extension, for example /News/pics/cat.png can be loaded with img:pics/cat.
It is also possible to load images from the /Textures folder. This is useful when you are using the image elsewhere in your mod as a texture. Just specifying the path relative to the /Textures folder will work. E.g.: /Textures/cat.png loads with img:cat. The same approach also works with resources built into the base game.
Several images can be displayed in a horizontal sequence by separating their name with a comma.
Example: img:imgOne,imgTwo,imgThree
The maximum width of the content area is 572 pixels. Wider images will be cropped.
The pipe character immediately followed by caption: allows to append a block of text to the right side of an image or image sequence. The text will be aligned vertically to the image, and the height of the block will be limited by the height of the image.
Example: img:imageName|caption:This is a caption.
When dev mode is enabled, a hamburger menu button appears in the title of each update news entry. The menu contains tools to interact with the update news system: setting the last seen news item version for your mod, opening the news popup and setting the "new player" status.
Pressing the F5 key will reload all news defs, which is very handy when composing news content.
All of these tools are only available in the extended update news window available via Options > Mod Options > All mod update news. There is also a keyboard shortcut for opening the window, although it is unassigned by default.
