Multi-Chapter Mod Resource Pack Reference Guide

Not really a 'guide' per-se, more like psuedo-documentation for the resource pack.
Small disclaimer; I'm not fantastic at writing documentation, so apologies if anything is not as clear as it ought to be.
You may find it helpful to simply 'mess around' with the resource pack to figure out how things work.

Preamble

This guide assumes you have intermediate to advanced knowledge of the AHiT modding tools, and that you're already familiar with the following:

• Map creation
  
• Kismet sequences
  
• Regular chapter mods
  
• Content packages
  
• Localization strings/files
  
• Custom classes

This guide is tailored to my Multi-Chapter Mod Resource Pack, though parts of it may be able to be adapted elsewhere.
This guide also makes some references to the example mod I created to showcase parts of the resource pack. I would recommend downloading its source files to get a better understanding of how certain things work.

Also, despite being designed for use in multi-chapter mods, several resources in the pack should be fine to use in regular chapter mods (e.g. Time Rift Portals, TimeObject_Mods in certain cases, several Kismet nodes).

If you have any problems related to the resource pack or the example mod, please leave a comment on their respective Workshop pages detailing the issue so I can attempt to fix it.

Setting Up the Resource Pack

Before you begin creating any multi-chapter mods, you'll need to decide how you want to utilise the resource pack.

There are currently two ways to use the pack in your mods:

Method 1 (Recommended)

Simply copy the following from the Multi-Chapter Mod Resource Pack Workshop directory:

• ../Classes/
  
• ../Globals.uci

and paste them into your own mod's directory (you can place the classes in a sub-directory if you wish to keep them separate from your own custom classes). Globals.uci must be placed in your mod's root directory (i.e. ../Mods/MyMod/Globals.uci).

Compile your scripts and you're ready to go.

If you happen to be working on multiple projects at once that all use the resource pack, make sure you delete all CompiledScripts directories of the mods that aren't being worked on (or just move the whole mod into ../HatinTimeGame/Mods/Disabled) and re-compile the scripts of the mod you're actively working on. If you don't, the editor may will get upset with you.

Method 2

After downloading the resource pack, copy the whole pack's Workshop directory into your ../HatinTimeGame/Mods/ directory (NOT your multi-chapter mod's directory).
Rename it to 'MultiChapterModResources', and delete the CookedPC directory inside it.

Compile its scripts and you're ready to go.

Anyone who wants to play your mod will be required to download the resource pack on the Workshop in addition to your mod. Remember to mark it as a required item on your Workshop page.



Method 2 means you won't need to manually update your own mods every time the resource pack is updated by me (e.g. if something breaks after an official update).
However, there are also a number of limitations with Method 2, most notably; the inability to make any modifications to, or extend from, the pack's classes.
There is also the issue of only being able to see one mod's actor classes at a time within the editor (whichever mod was compiled latest is the one that'll have its actors appear), which would be rather inconvenient if you plan to have your own custom actor classes in your mod.

With the current state of the modding tools, I would recommend using Method 1 if you plan on creating any of your own custom actor classes, or wish to modify/extend the resource pack classes.

ChapterInfo & ChapterActInfo

Chapter(Act)Infos still behave the same, though there are a few things that I want to briefly mention.

I'll be using Heavy & Co's 'Making a Chaper' guide as a baseline reference: https://steamcommunity.com/sharedfiles/filedetails/?id=1438805450

All your ChapterInfos/ChapterActInfos MUST be in the same content package, no exceptions.

ChapterInfo

• Unlocked By Level Bit - This isn't for unlocking the chapter itself, it's for unlocking individual acts. It's only relevant for chapters that have their acts unlocked by Snatcher contracts. Custom contracts are not covered by this resource pack.
  
• Is Actless - If this quirk is set, ChapterActInfo Act Names must be localization strings referencing a line under the '[Mountains]' header in ../ModFolder/Localization/INT/HatinTimeGame.int.
  
• Is Standoff - If you're creating a Standoff chapter, its Finale ChapterActInfo must explicitly have all other acts set as required acts, or else the transition from a standard act select menu to a standoff act select menu will not behave correctly.
  
• Has Free Roam - Normally, this quirk would be completely non-functional. However, with the resource pack, I have restored its functionality somewhat. Simply create a ChapterActInfo with ActID 99, and set its Pon Cost to the number of non-Time Rift acts the player must complete in that chapter to unlock it.
  
• Finale Act ID - Finales will function correctly with the resource pack's ActSelector telescopes.

ChapterActInfo

• Supports Highscore - Be sure this is set to false for your "studio" and "award ceremony" acts of any Standoff chapters you make. Should also be set to false for any Time Rift acts within Standoff chapters.
  
• Render Priority - Will determine the order in which act select menu icons update, usually best to just not change this.

ChapterInfo Package Size Limit

As you may already know, ChapterInfo packages have a size limit of 40mb. This can potentially become a problem for a multi-chapter mod, depending on how many custom title cards/time rift photos/overview photos you plan to include with your mod, all of which need to always be in memory.

Fortunately, there is a relatively simple workaround, though I would suggest that even with the ability to bypass the 40mb size limit that you should still aim to keep your cooked package sizes as small as possible.

The workaround is simple, and you can see it in action in the example mod.

1. Make a new content package in the editor, add/create your required assets, save and exit.
   
2. In the mod manager, under the 'Scripting' tab, set 'Chapterinfo' to 'MyContentPackage.'
   
   • The . is required.
3. Cook your mod (you can temporarily move all (except one) of your maps to speed up the cooking process if you'd like).
   
4. Copy the cooked package into some other temporary folder (if you leave it in CookedPC, it'll be wiped next time you cook).
   
   • As long as you don't make any modifications to this package in the editor, you can keep pasting in the same version after you cook the rest of your mod.
5. Set 'Chapterinfo' back to your main ChapterInfo package.

Now, whenever you want to test/update your mod, just cook as usual, then paste in your saved cooked content package(s) into CookedPC.

Making a Custom Hub

When creating a level to act as your custom hub, there are a few things to keep in mind:

• It MUST be the first map when sorting your maps alphabetically, this is how the resource pack determines which map is your hub. An easy way to achieve this is simply prefixing your map name with '0_'.
  
• A hub ChapterInfo is not mandatory, but will be required if you want a custom name/photo to appear on the pause screen.
  
• A hub ChapterActInfo is only necessary if players will be accessing your custom hub via the act select menu in the Spaceship's Mailroom, instead of being immediately loaded into the custom hub map.
  
• Keep it fairly small and with loading times as short as possible, as players will be continually returning to it.
  
• For added player convenience, you may wish to place 'Hat_PlayerStart' actors near each of your ActSelector actors with a corresponding Checkpoint ID so that players will spawn there after returning from any of your chapters. Do not use the Chapter parameter, it will not function correctly, as the current chapter will always be reset to 99 when returning to the custom hub.

You will also require a few specific actors for your ActSelector's menus to function correctly. I have created a "prefab" of sorts that you can copy from.[gist.githubusercontent.com] Just copy all the text from that page, and paste it straight into your custom hub in the editor, then just move it somewhere out of the way. The hidden volume is there for convenience, if you would like to handle hiding the actors in a different way, you can remove it. Do NOT rotate any of the actors. The act select menu class does not account for different rotations.

I would recommend taking a look at the custom hub included with the example mod to get an idea of how you might set things up (especially for the Kismet stuff).

If you'd like players to be immediately loaded into your custom hub, instead of bringing up an act select menu in the Mailroom, simply omit your ChapterInfo when setting 'Chapterinfo' in the mod manager. e.g. 'MyChapterInfoPackage.' (the . is required).

Making Credits Sequences

NOTE: You cannot make custom credits if you set up the resource pack using 'Method 2', as you will not be able to modify/extend any classes.

You can override functions if you wish, but only a defaultproperties block is required for any credits subclasses.

Intro Credits

Intro credits are relatively easy to make.
Extend Hat_HUDElementOverlaySoftCredits_Mods into your own sub-class, then simply add your own credits entries to the Credits array in your subclass' defaultproperties:

defaultproperties
{
	//Clears superclass Credits array.
	Credits.Empty;
	
	Credits.Add((Title="First Title", Name="First Name"));
	Credits.Add((Title="Second Title", Name="Second Name"));
	//etc.
}

Take a look at the Hat_HUDElementOverlaySoftCredits_Mods source file to see everything you're able to customise. I've also included a few preset color struct macro defines for added convenience. (NOTE: You'll need to copy the defines into your sub-class, as macros are not inherited by sub-classes, sorry!)

Once you've compiled your scripts, just hook up an Open HUD Kismet node in your level and select your credits subclass.

End Credits

The ending credits themselves are just as easy to make as intro credits, though actually rendering them can be slightly more complicated.
Like the intro credits, you'll want to extend Hat_HUDMenuEndingCredits_Mods into your own subclass where you'll add your mod specific credits:

defaultproperties
{
	//Clear superclass' default credits.
	EndingCredits.Empty;
	
	EndingCredits.Add((Title = "AN A HAT IN TIME MOD", Lead = "by Some People"));

	EndingCredits.Add((Title = "CREATED BY", Lead = "Some Person"));
	EndingCredits.Add((Title = "TEAM A", Lead = "Team A Director", Subs = ("A Member") ));
	//etc.
}

Ending credits don't have any extra customisable features like intro credits (feel free to make your own though), so you only need to add Title, Lead, and Subs values.

Once you've compiled your scripts, you have two ways of displaying your credits to the player.
First, is simply opening it via an Open HUD Kismet node; this will just render your credits directly on the player's screen.

The other method is putting a Hat_DynamicStaticActor_Movable actor tagged as "CreditsPlane" that has Material'HatinTime_Levels_Credits.Materials.CreditsText' applied to it in your level, then when you open your credits HUD it'll render itself on that actor, like in the base game.

There's a few other nuances with ending credits that I haven't mentioned, I'd highly recommend taking a look at the example mod's credits map to get a better understanding of them. I've also created a "prefab" of sorts that you can just paste in to your map[gist.githubusercontent.com] if you want to mimic the base game credits. (Does not include Kismet sequence setup)

I've also included an extra feature that may be useful for a playable end credits sequence.
If you add "SetPlayerDepth = true;" to your subclass' defaultproperties, sending Show/HideBlackBackground menu commands to your subclass will then also change the player's DepthPriorityGroup in addition to your 'BackgroundPlane'/'CreditsPlane' tagged actors.

Making a MuMission (Playable Mustache Girl sequence)

The MuMission

Place a Hat_Player_MustacheGirl actor wherever you want the player to start during the MuMission. Either make it hidden by default, or set up your Kismet sequence to destroy it if player is not in a MuMission. It'll complain about not being in a pylon, but you don't need to place one, since it'll only be controlled by the player anyway.

In your Hub, add a Hat_SeqCond_IsModMuMission Kismet node that will trigger before your usual intro stuff (intruders/powerpanels/telescopes). If you're using the resource pack via 'Method 2', you'll need to specify the ChapterInfo of the chapter that the player must unlock to trigger the MuMission in the node. If you're using 'Method 1', simply modify the 'FinaleChapterInfo' macro in your Globals.uci file, replacing 'None' with an object reference to your ChapterInfo and recompile, it will override the default value in Hat_SeqCond_IsModMuMission, which is used if no ChapterInfo is passed to it.

Then, hooked up to the 'True' output of your Hat_SeqCond_IsModMuMission node, you'll want:

1. Teleport Players node (teleport players somewhere out of sight)
   
2. Toggle Hidden (hide all players/unhide Mustache Girl)
   
3. Toggle HUD Element node (All players, Hide Hat_HUDElementObjectives, so co-op head icon doesn't appear)
   
4. Possess Pawn node (Player 0, your Mustache Girl actor)
   
5. Mission Intro - HUB node (Intruder Alert enabled)
   
   Hooked up to the 'Finished' output:
   • Set Exclusive Splitscreen node (Player 0)
     
   • Toggle Cinematic Mode node (Player 1, all options enabled)

You may also want to hook up a few extra nodes to deal with actors that Mustache Girl should not be able to interact with.

For example:

• GoToState node with 'complete' state targeting Hat_SpaceshipPowerPanel classes. Will "close" the powerpanels and prevent Mustache Girl from entering their associated doors.
  
• Toggle node targeting Hat_SpringDoors to prevent Mustache Girl going through them, or on Hat_ActSelector_Mods to disable act select telescopes.
  
• Destroy node to just destroy anything that shouldn't be there during the MuMission.

The Loading Screen Transition

The MuMission loading screen is entirely optional, Hat_SeqCond_IsModMuMission in your hub will still function perfectly fine without it.

To have the loading screen transition to the MuMission loading screen, the player must return to your custom hub via either:

• Hat_TimeObject_Mods (or a subclass)
  
• Hat_SeqAct_ReturnToCustomHUB node

It cannot trigger if the player enters via the Mailroom.

To let the resource pack know which chapter is your "Finale" chapter, you can either:

• Manually set your ChapterInfo on every TimeObject_Mods actor/ReturnToCustomHUB node
  
• Set the 'FinaleChapterInfo' macro define in Globals.uci to your ChapterInfo, then leave any MuMission ChpaterInfo fields blank. (Only works if utilising the resource pack via Method 1)
  
  
  If you want to test either the loading screen or the MuMission quickly, you can add the "ForceModMuMission" actbit to force it.

"API" Reference

I'm using "API" rather loosely here, but this section basically covers all the custom classes and what they do/(sort of) how to use them. (If I missed anything let me know!)

Split into multiple sections due to the character limit.

Actors

Hat_ActSelector_Mods
• Subclass of Hat_ActSelector. This is what players will use to access all of your mod's chapters. Remember to assign it a ChapterInfo.
  
• By default it'll require the player to trigger a Power Panel to activate, but you can also have it simply appear automatically once the player has unlocked it.
  
• Colour is set via material overrides on 'Mesh' and 'Telescope Scope'. Default colour materials are located in 'HatInTime_HUB_H.Materials'. Custom colour materials should be instances of 'HatInTime_HUB_H.Materials.Telescope'
  
• Note: Kid's Hat will still target these, but only if the player has not collect all Time Pieces in the base game.

Hat_Enemy_TimeRiftBall_Mods
• Subclass of Hat_Enemy_TimeRiftBall. Spawns a Hat_TimeObject_Mods instead of a Hat_TimeObject_TimeRift.
  
• Also has more options to fine tune the behaviour of the spawned Time Piece.

Hat_MonitorTimePieces_Mods
• Recreation of Hat_MonitorTimePieces, since you can't extend non-alwaysloaded classes.
  
• Displays player's current collected Time Piece count of your mod. Just place it somewhere in your level(s).

Hat_SpaceshipPowerPanel_Mods
• Subclass of Hat_SpaceshipPowerPanel.
  
• Will correctly check if a mod chapter is unlocked.
  
• Number displayed is set via a material override. Any custom power panel screen materials you make should be instances of 'HatinTime_Spaceship.PowerPanels.Materials.PowerPanel_Locked'.

Hat_TimeObject_Mods
• Subclass of Hat_TimeObject.
  
• Will return player to your custom hub on collection (can be disabled).
  
• Can set a checkpoint on collection.
  
• Calls custom HUDElements for storybook pages and rift roulette that will send player back to your custom hub when they end.
  
• Calls custom ActHighscore HUDElement to correctly set act highscores for mod acts, and also sends player back to your custom hub.
  
• Has option to bypass the 7 Time Pieces per mod limit. Will manually add itself to the TimeObjects array in the player's save data if it was not added normally.
  
• Will trigger MuMission loading screen when returning to your custom hub (if you have it set up to do so).
  
• Contains functionality of Hat_TimeObject_TimeRift as well.

Hat_TimeObject_Cluster_Mods
• Subclass of Hat_TimeObject_Mods.
  
• Functionally identical, but has preset stuff for a Time Piece cluster.

Hat_TimeObject_Alps_Mods
• Subclass of Hat_TimeObject_Mods. Intended for use with Actless chapters.
  
• It's like Hat_TimeObject_Alps, but with mod support.
  
• Will trigger the chapter's Finale even without Toxic Flower actors set, though the final mountain peak will not play its "You cleared blah blah peak" message in this case.

Hat_TimeRiftPortal_Mods
• Clone of Hat_TimeRiftPortal, as you cannot extend non-alwaysloaded classes.
  
• Correctly disappears if already completed.
  
• Has added option to not disappear on completion.
  
• Purple Rifts will require using Hat_SeqAct_SetTimeRiftUnlocked or Hat_SeqAct_TimeRiftCutscene to unlock.

HUDMenus/HUDElements

Hat_HUDMenuActSelect_Mods
• Used by Hat_ActSelector_Mods.

Hat_HUDElementActHighscore_Mods
• Used by Hat_TimeObject_Mods for Standoff chapter acts that support highscores.

Hat_HUDMenu_StoryBookPages_Mods
• Used by Hat_TimeObject_Mods for Time Rift Time Pieces with storybook pages.

Hat_HUDMenuTimeRiftRoulette_Mods
• Used by Hat_TimeObject_Mods and Hat_HUDMenu_StoryBookPages_Mods for mod Time Pieces with 'Reward Item' checked.

Hat_HUDElementOverlaySoftCredits_Mods
• Recreation of Hat_HUDElementOverlaySoftCredits for mod specific credits.
  
• Think of this as sort of a 'base' class. You should extend it into another class with your mod-specific credits.
  
• To trigger your intro credits, just add an Open HUD Kismet node and select your credits HUD.

Hat_HUDMenuEndingCredits_Mods
• Recreation of Hat_HUDMenuEndingCredits for mod specific credits.
  
• As above, this is sort of a 'base' class. You should extend it into another class with your mod-specific credits.
  
• To trigger your end credits, just add an Open HUD Kismet node and select your credits HUD.
  
• By default, the credits will just render directly on the player's screen. If you want them to appear "in the world" like in the base game, you'll need a few extra actors. See the "Making Credits Sequences" section for more info.

Misc

Hat_GameManager_Mods
• Contains a few important functions called by the other classes.
  
• Not really used as a real GameManager, more of a glorified include file.

Globals.uci
• Contains project-wide macros.

"API" Reference - Kismet Nodes

Sequence Actions

Hat_SeqAct_ResetLevelBits
• Will remove all levelbits from specified map(s).
  
• Also has an option to reset actbits.

Hat_SeqAct_ResetModChapterProgress
• Will reset progress of specified ChapterInfos.
  
• Resets collected Time Pieces, levelbits of maps referenced by ChapterActInfos, and any Purple Rifts that were unlocked.
  
• Note: If you have any maps that are not directly referenced by a ChapterActInfo, you'll need to use a Hat_SeqAct_ResetLevelBits node to reset their levelbits.

Hat_SeqAct_ReturnToCustomHUB
• Returns the player to your mod's hub level.
  
• Will trigger a MuMission loading screen if the player has unlocked it (e.g. returning from an Actless chapter).

Hat_SeqAct_SetModDeadBirdWinner
• Sets a ModDeadbirdWinner levelbit on the specified map.
  
• You should always target your Standoff chapter's finale map, as that is what Hat_HUDMenuActSelect_Mods will check/set to determine a mod chapter's winner.

Hat_SeqAct_SetTimePiece
• Manually add or remove a mod Time Piece from the player.
  
• Useful for debugging purposes.

Hat_SeqAct_SetTimeRiftUnlocked
• Manually unlock or lock a Purple Time Rift (or a Blue Hub Rift).

Hat_SeqAct_TimeRiftCutscene
• A stand-in for custom relics. Will trigger the Purple Rift unlock cinematic on the ActSelector that contains the specified Time Rift.
  
• Will automatically unlock the Time Rift, you don't need to manually unlock them first (unless you're unlocking more than one rift at a time on the same ActSelector).

Hat_SeqAct_SwitchModHUBMission
• Based on Hat_SeqAct_SwitchHUBMission.
  
• Used to determine which intro cinematic to play in the hub.
  
• Take a look at the example map for a practical example.

Hat_SeqAct_SwitchModHUBIntruder
• Used to determine which Intruder Alert intro cinematic to play in the hub.
  
• As above, take a look at the example map for a practical example.
  
• Will only trigger intruder outputs if an intruder levelbit has been set.

Hat_SeqAct_SetModIntruderAlert
• Sets custom intruder states that can be read by Hat_SeqAct_SwitchModHUBIntruder and Hat_SeqCond_HasModIntruderAlert.
  
• Supports 4 states: Locked, Trigger Alert, Alert Seen, Interacted With.

Sequence Conditions

Hat_SeqCond_HasModIntruderAlert
• Reads custom intruder states that can be set by Hat_SeqAct_SwitchModHUBIntruder and Hat_SeqAct_SetModIntruderAlert.

Hat_SeqCond_ModDeadBirdWinner
• Gets the Standoff winner levelbit of the specified map (if any).
  
• As with Hat_SeqAct_SetModDeadBirdWinner, you should always use your Standoff chapter's finale map.

Hat_SeqCond_ModChapterUnlocked
• Checks whether a mod chapter has been unlocked by the player.

Hat_SeqCond_ModActUnlocked
• Checks whether a mod act has been unlocked by the player.

Hat_SeqCond_MinimumModTimeObjects
• Checks whether the player's current collected Time Piece count of your mod meets the specified threshold.
  
• Also has an int variable link that outputs the player's current Time Piece count.

Hat_SeqCond_IsTimeRiftUnlocked
• Check if a Purple Time Rift has been unlocked.

Hat_SeqCond_IsModMuMission
• Check if player should trigger/is in a hub MuMission.
  
• If you want to force a MuMission, set the the "ForceModMuMission" actbit to a value of 1.

Hat_SeqCond_IsModActlessFinale
• Used within Actless chapters to change parts of the level/trigger certain events only during its finale act.

Hat_SeqCond_HasUntouchedModChapter
• Identical to Hat_SeqCond_HasUntouchedChapter except with mod chapter support.
  
• Chapters are considered 'untouched' if the player has unlocked them, but has not obtained the specified threshold of Time Pieces from that chapter yet.

Hat_SeqCond_HasModChapterTimePieces
• Like Hat_SeqCond_MinimumModTimeObjects, but for a specific chapter.
  
• Has an option to exclude Time Rift Time Pieces.

Resource Links

Workshop Pages

• Multi-Chapter Mod Resource Pack
  
• Multi-Chapter Example Mod (Source download is linked in its description)

"Prefabs"

Copy all text and paste into your editor window.

• Act Select Menu actors[gist.githubusercontent.com]
  
• Ending Credits actors[gist.githubusercontent.com]

Templates/Misc

• Polaroid Photos[drive.google.com] (for Time Rift/pause menu photos)
  
• Power Panel numbers[drive.google.com] (comes with several pre-made numbers ready to import)