diff --git a/docs/modding/linux/meta.json b/docs/modding/linux/meta.json index 57b0c2f5..21d50ff7 100644 --- a/docs/modding/linux/meta.json +++ b/docs/modding/linux/meta.json @@ -1,4 +1,4 @@ { "title": "Modding on Linux", - "weight": 30 + "weight": 100 } diff --git a/docs/modding/p2ce-campaigns/commands-convars-and-launch-options.md b/docs/modding/p2ce-campaigns/advanced/commands-convars-and-launch-options.md similarity index 94% rename from docs/modding/p2ce-campaigns/commands-convars-and-launch-options.md rename to docs/modding/p2ce-campaigns/advanced/commands-convars-and-launch-options.md index 041e44d2..bb757724 100644 --- a/docs/modding/p2ce-campaigns/commands-convars-and-launch-options.md +++ b/docs/modding/p2ce-campaigns/advanced/commands-convars-and-launch-options.md @@ -1,77 +1,80 @@ ---- -title: Various ConCommands, ConVars, and Launch Options -features: - - USE_CAMPAIGNMANAGER ---- - -# Various ConCommands, ConVars, and Launch Options - -## Useful Commands - -### `campaign_reload` - -Reloads the campaign list. New & change campaign scripts should appear in the UI. If you are on the campaign selection screen, re-enter that screen to see the new/update campaign. - -### `campaign_info` - -Spews information about the current campaign into the console. - -### `campaign_list` - -Lists all campaigns detected by P2:CE to the console. - -### `campaign_clear` - -Clears the currently active campaign. - -### `campaign_continue` - -Continue a campaign from the latest save. Usage: `campaign_continue [campaign_id]`. - -### `campaign_level_next` - -Changes the map to the next level in the campaign, if it exists. - -### `campaign_level_prev` - -Changes the map to the previous level in the campaign, if it exists. - -### `campaign_savedata_reset` - -Wipes all save data relating to campaign progression. Does not delete saved game files. - -### `campaign_savedata_show` - -Display save data relating to campaign progression. - -### `campaign_set_active` - -Set a specified campaign as active. Usage: `campaign_set_active [campaign_id]` - -### `campaign_start` - -Starts a specified campaign at a certain chapter. Usage: `campaign_start [campaign_id] [chapter_index]` - -### `startupmenu` - -Enters the appropriate background map as detailed by the campaign script. - -## Useful Cvars - -### `campaign_debug` - -If value is 1, prints additional debugging information to the console in relation to the campaign system. - -### `campaign_default` - -Sets the default campaign to boot into on startup. The background map will be entered automatically without intervention by a script. - -## Useful Launch Options - -### `-unlockchapters` - -Treats all campaigns as completely unlocked for testing. This does not make any changes to the progression save. Must be used in conjunction with the `-dev` launch option. - -### `-nochapterprogress` - -Treats all campaigns as completely locked for testing. This does not make any changes to the progression save. Must be used in conjunction with the `-dev` launch option. \ No newline at end of file +--- +title: Various ConCommands, ConVars, and Launch Options +features: + - USE_CAMPAIGNMANAGER +--- + +# Various ConCommands, ConVars, and Launch Options + +## Useful Commands + +### `campaign_reload` + +Reloads the campaign list. New & change campaign scripts should appear in the UI. If you are on the campaign selection screen, re-enter that screen to see the new/update campaign. + +### `campaign_info` + +Spews information about the current campaign into the console. + +### `campaign_list` + +Lists all campaigns detected by P2:CE to the console. + +### `campaign_clear` + +Clears the currently active campaign. + +### `campaign_continue` + +Continue a campaign from the latest save. Usage: `campaign_continue [campaign_id]`. + +### `campaign_level_next` + +Changes the map to the next level in the campaign, if it exists. + +### `campaign_level_prev` + +Changes the map to the previous level in the campaign, if it exists. + +### `campaign_savedata_reset` + +Wipes all save data relating to campaign progression. Does not delete saved game files. + +### `campaign_savedata_show` + +Display save data relating to campaign progression. + +### `campaign_set_active` + +Set a specified campaign as active. Usage: `campaign_set_active [campaign_id]` + +### `campaign_start` + +Starts a specified campaign at a certain chapter. Usage: `campaign_start [campaign_id] [chapter_index]` + +### `startupmenu` + +Enters the appropriate background map as detailed by the campaign script. + +## Useful Cvars + +### `campaign_debug` + +If value is 1, prints additional debugging information to the console in relation to the campaign system. + +### `campaign_default` + +Sets the default campaign to boot into on startup. The background map will be entered automatically without intervention by a script. + +## Useful Launch Options + +### `-unlockchapters` + +Treats all campaigns as completely unlocked for testing. This does not make any changes to the progression save. Must be used in conjunction with the `-dev` launch option. + +### `-nochapterprogress` + +Treats all campaigns as completely locked for testing. This does not make any changes to the progression save. Must be used in conjunction with the `-dev` launch option. + +### `-campaign "[campaign_id]"` +Automatically loads into a campaign on startup. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/advanced/meta.json b/docs/modding/p2ce-campaigns/advanced/meta.json new file mode 100644 index 00000000..3b846826 --- /dev/null +++ b/docs/modding/p2ce-campaigns/advanced/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Advanced", + "weight": 100 +} diff --git a/docs/modding/p2ce-campaigns/technical-notes.md b/docs/modding/p2ce-campaigns/advanced/technical-notes.md similarity index 84% rename from docs/modding/p2ce-campaigns/technical-notes.md rename to docs/modding/p2ce-campaigns/advanced/technical-notes.md index d6501e20..1a11f9be 100644 --- a/docs/modding/p2ce-campaigns/technical-notes.md +++ b/docs/modding/p2ce-campaigns/advanced/technical-notes.md @@ -1,78 +1,70 @@ ---- -title: Technical Notes -features: - - USE_CAMPAIGNMANAGER ---- - -# Technical Notes - -> [!NOTE] -> This article includes technical notes, relevant to users developing sourcemods, with the intent of rolling their own UI script code. - -# Reusing P2:CE's UI - -P2:CE's UI code was designed to be initially reused by sourcemods in the event that you cannot or do not want to roll your own UI script code. If the `campaign_default` convar is specified in `cfg/cvar_defaults.cfg`, the game will enter the campaign menu and use it as the base menu, meaning that the player cannot exit to the P2:CE's default menu. It will work with the campaign system and you can focus your efforts elsewhere until you decide to write your own menus. - -# Campaign Progression - -Campaigns have their progression information saved inside `SAVE/campaign_save_data.kv3`. This file can be erased using the `campaign_savedata_reset` command. Campaign progression is currently tracked by chapter & map number. - -# Meta Keys - -The meta block found in the campaign script is a generic block internally. The engine does not define the fields that this Wiki documents. Instead, these keys are required by P2:CE's Panorama UI code. - -In TypeScript, the meta block is represented as a `Map`, and keys are retrieved using `meta.get('key')`. If you roll your own UI code with no intention of reusing P2:CE's scripts, **none** of the meta keys (and subsequently the art asset specifications) documented by the Wiki will apply to your code. You **MUST** reimplement these keys and use them where you see fit. However, this also means that if you have other use cases for your Sourcemod, you can add keys yourself! - -> [!WARNING] -> Meta blocks cannot have blocks nested inside. Do not attempt to do so if you are implementing a custom menu script. - -# Campaign Value Fixup - -> [!NOTE] -> **This applies to all campaign script values, but predominantly the meta values.** - -When requesting a value from the campaign system, be it a chapter title, map name, or meta value (e.g. author, chapter display mode), it will return *exactly* what is specified by the script. There is no fixup for any value by the engine internally (excluding sanitization). - -For example, take the following campaign script snippet: -``` -{ - campaigns = { - "portal2_sp" = { - title = "#MainMenu_Campaigns_portal2" - meta = { - author = "#MainMenu_Campaigns_Valve_Author" - desc = "#MainMenu_Campaigns_portal2_Description" - box_art = "{campaign_art}/portal2/boxart.png" - } - } - } -} -``` - -The reference guide postulates that the `title` key will be localized if the value is a valid localization token. While this is true for P2:CE proper, **this is not the case for custom UI code.** P2:CE's UI code localizes the `title` value by itself, which is frontend functionality **and is not provided by the engine.** This means that if you were to write your own UI code and retrieve the `title` key, you would get `#MainMenu_Campaigns_portal2` returned to you, **not** the localized string. For any value that needs fixup, that functionality must be reimplemented by your sourcemod's UI code. - -**This is especially important for any value that provides an image asset path.** - -To reduce friction of creating campaign scripts, P2:CE's UI code will build asset paths for campaign authors. The UI code builds a path for an addon like this: `file://[addon path]/.assets/[asset value in script]` (except for movie assets). Like the example prior, if you write your own UI code, you will have to reimplement this functionality yourself to what you expect, or write paths in the campaign script values themselves. - -Campaigns bundled with the game itself (and **not** as a local addon) will refer to asset paths using `{named_paths}`. The above snippet uses this for `box_art`. This is a shorthand for asset paths in Panorama and these named paths are defined in `panorama/panorama.cfg`. - -# API Documentation - -Full documentation of the Campaigns API and interfacing it with Panorama can be found in the Panorama Types repository, located [here](https://github.com/StrataSource/pano-typed). - -# Campaign Bucketing - -Internally, campaigns are organized via buckets, where a bucket denotes the source of the campaign. This helps avoid ID string conflicts. The `campaign_list` console command will display campaigns and their respective buckets. - -The following buckets are used: - -- `base`: This bucket represents campaigns found within the game's `script/campaigns.kv3` file, the folder in which `gameinfo.txt` resides. -- `addon:[ADDON_FOLDER]`: This bucket represents campaigns found within a local addon. A separate bucket is created for each local addon. -- `workshop:[WORKSHOP_ID]`: This bucket represents campaigns found within an addon from the Steam Workshop. A separate bucket is created for each Workshop addon. - -When you reference an addon through an API, the ideal method is to make a full reference, created as: `[BUCKET_ID]/[CAMPAIGN_ID]`. - -For example, for the Portal 1 campaign, which is a locally shipped addon: `addon:portal1_sp/portal1_sp`. - -For a campaign shipped in the base game's files: `base/my_cool_campaign` *(This is probably what you will use a lot if you need to interface with the Campaigns API and you are rolling your own UI)* +--- +title: Technical Notes +features: + - USE_CAMPAIGNMANAGER +--- + +# Technical Notes + +> [!NOTE] +> This article includes technical notes, relevant to users developing sourcemods, with the intent of rolling their own UI script code. + +# Meta Keys + +The meta block found in the campaign script is a generic block internally. The engine does not define the fields that this Wiki documents. Instead, these keys are required by P2:CE's Panorama UI code. + +In TypeScript, the meta block is represented as a `Map`, and keys are retrieved using `meta.get('key')`. If you roll your own UI code with no intention of reusing P2:CE's scripts, **none** of the meta keys (and subsequently the art asset specifications) documented by the Wiki will apply to your code. You **MUST** reimplement these keys and use them where you see fit. However, this also means that if you have other use cases for your Sourcemod, you can add keys yourself! + +> [!WARNING] +> Meta blocks cannot have blocks nested inside. Do not attempt to do so if you are implementing a custom menu script. + +# Campaign Value Fixup + +> [!NOTE] +> **This applies to all campaign script values, but predominantly the meta values.** + +When requesting a value from the campaign system, be it a chapter title, map name, or meta value (e.g. author, chapter display mode), it will return *exactly* what is specified by the script. There is no fixup for any value by the engine internally (excluding sanitization). + +For example, take the following campaign script snippet: +``` +{ + campaigns = { + "portal2_sp" = { + title = "#MainMenu_Campaigns_portal2" + meta = { + author = "#MainMenu_Campaigns_Valve_Author" + desc = "#MainMenu_Campaigns_portal2_Description" + box_art = "{campaign_art}/portal2/boxart.png" + } + } + } +} +``` + +The reference guide postulates that the `title` key will be localized if the value is a valid localization token. While this is true for P2:CE proper, **this is not the case for custom UI code.** P2:CE's UI code localizes the `title` value by itself, which is frontend functionality **and is not provided by the engine.** This means that if you were to write your own UI code and retrieve the `title` key, you would get `#MainMenu_Campaigns_portal2` returned to you, **not** the localized string. For any value that needs fixup, that functionality must be reimplemented by your sourcemod's UI code. + +**This is especially important for any value that provides an image asset path.** + +To reduce friction of creating campaign scripts, P2:CE's UI code will build asset paths for campaign authors. The UI code builds a path for an addon like this: `file://[addon path]/.assets/[asset value in script]` (except for movie assets). Like the example prior, if you write your own UI code, you will have to reimplement this functionality yourself to what you expect, or write paths in the campaign script values themselves. + +Campaigns bundled with the game itself (and **not** as a local addon) will refer to asset paths using `{named_paths}`. The above snippet uses this for `box_art`. This is a shorthand for asset paths in Panorama and these named paths are defined in `panorama/panorama.cfg`. + +# API Documentation + +Full documentation of the Campaigns API and interfacing it with Panorama can be found in the Panorama Types repository, located [here](https://github.com/StrataSource/pano-typed). + +# Campaign Bucketing + +Internally, campaigns are organized via buckets, where a bucket denotes the source of the campaign. This helps avoid ID string conflicts. The `campaign_list` console command will display campaigns and their respective buckets. + +The following buckets are used: + +- `base`: This bucket represents campaigns found within the game's `script/campaigns.kv3` file, the folder in which `gameinfo.txt` resides. +- `addon:[ADDON_FOLDER]`: This bucket represents campaigns found within a local addon. A separate bucket is created for each local addon. +- `workshop:[WORKSHOP_ID]`: This bucket represents campaigns found within an addon from the Steam Workshop. A separate bucket is created for each Workshop addon. + +When you reference an addon through an API, the ideal method is to make a full reference, created as: `[BUCKET_ID]/[CAMPAIGN_ID]`. + +For example, for the Portal 1 campaign, which is a locally shipped addon: `addon:portal1_sp/portal1_sp`. + +For a campaign shipped in the base game's files: `base/my_cool_campaign` *(This is probably what you will use a lot if you need to interface with the Campaigns API and you are rolling your own UI)* diff --git a/docs/modding/p2ce-campaigns/campaign-progression.md b/docs/modding/p2ce-campaigns/campaign-progression.md new file mode 100644 index 00000000..712c2759 --- /dev/null +++ b/docs/modding/p2ce-campaigns/campaign-progression.md @@ -0,0 +1,10 @@ +--- +title: Campaign Progression +features: + - USE_CAMPAIGNMANAGER +weight: 2 +--- + +# Campaign Progression + +Campaigns have their progression information saved inside `SAVE/campaign_save_data.kv3`. This file can be erased using the `campaign_savedata_reset` command. Campaign progression is currently tracked by chapter & map number. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/getting-started.md b/docs/modding/p2ce-campaigns/getting-started.md deleted file mode 100644 index 2d1d3704..00000000 --- a/docs/modding/p2ce-campaigns/getting-started.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Getting Started -features: - - USE_CAMPAIGNMANAGER ---- - -# Getting Started with P2:CE Campaigns - -![Campaign Selection UI](images/campaign-selection-screen.webp) - -P2:CE includes the ability for sourcemods, mappers, and addon authors to create custom campaigns. These custom campaigns can then be published to the Steam Workshop. A campaign refers to an organized bundle of maps, which could be tightly related (such as story-based campaigns) or have no relation at all (map/competition packs). - -P2:CE's campaign system is the primary form of user created playable content. Standalone maps are still available, but are folded into a "P2:CE Workshop" campaign as a playlist. - -# Creation - -A campaign addon is much like a standard addon. It will contain all required assets, and optionally link to other external dependencies on the Steam Workshop. Campaign addons ship with additional image assets that the game's menu will use in various locations. - -To begin, [create a new addon](/modding/workshop/workshopgui) and include all required content. Next, create a `campaigns.kv3` file within the `scripts` folder of the addon. This will define the campaign to the game. - -Each campaign has a subset of metadata that all dictate your how your chapters are ordered and unlocked, and what art assets are used. The campaign script is a KeyValue3 file, structured in the following way: - -> [!NOTE] -> This snippet is valid syntax, but you must replace the placeholder values with your own, or it will not work in P2:CE! -> -> An example of a functioning campaign script is available [here](https://github.com/StrataSource/p2ce-addons/blob/main/portal2/scripts/campaigns.kv3). - -``` -{ - meta = { - (asset information) - } - "campaigns" = { - "CAMPAIGN_ID" = { - title = (string) - unlock_all = (boolean) - meta = { - (overrides) - } - chapters = [ - // chapter block - { - title = (string) - save_comment = (string) - meta = { - (overrides) - } - maps = [ - // map entry - { - name=(string) - meta = { - (overrides) - } - } - ] - }, - // etc. - ] - } - } -} -``` -In order: -- `meta`, a block that details information for P2:CE to use in its menu presentation and loading screens. - - Meta keys are unique to the respective mod and it is up to the menu script to recognize and use them. - - Meta blocks can exist at the Root/Campaign/Chapter/Map level. Priority is established in reverse order. - - Matching fields inside the meta block will override based on this priority. For example, `background_map` specified at the chapter level overrides that field at the campaign or root level. - - Full meta keys for P2:CE are described in the [Full Script Reference](/modding/p2ce-campaigns/script-reference#meta-keys) page. -- `campaigns`, top-level block that groups all campaigns provided by the addon together. -- `CAMPAIGN_ID`, an internal name to refer to the campaign by. -- `title`, a human readable name for the campaign/chapter. This string will be localized if a token is set. -- `unlock_all`, should all chapters be unlocked to start with? -- `chapters`, an array containing blocks that describe each chapter. - - `save_comment`, optional field that sets the save comment for saves created at the belonging chapter. - - `maps`, an array containing blocks that describe each map. - - Each map must specify the `name` field. - -Fill in as much information as possible in the above snippet, or copy the sample from the [Full Script Reference](/modding/p2ce-campaigns/script-reference#ideal-meta-locations) page. - -Duplicate the chapter block for each individual chapter. Duplicate the map block inside the `maps` array for every map that belongs to that chapter. - -For example: -``` -chapters = [ - // chapter block - { - title = "My Cool Chapter 1" - maps = [ - // map entry - { name="sp_a1_intro1" }, - { name="sp_a1_intro2" }, - // comma on the last entry in an array is valid syntax - { name="sp_a1_intro3" }, - ] - }, - { - title = "My Cool Chapter 2" - maps = [ - // map entry - { name="sp_a1_intro4" }, - ] - }, -] -``` - -If you are having trouble placing meta keys, or want a script to copy and paste, see the [Full Script Reference](/modding/p2ce-campaigns/script-reference#ideal-meta-locations) page. - -Once the campaign script has been created with the necessary information, it can be found in the campaign selector. - -The bare minimum script to have a campaign appear on the selector can be found below: -``` -{ - "campaigns" = { - "[CAMPAIGN_ID]" = { - } - } -} -``` -Required art assets will be replaced with one of several fallback images if they are not found. Art assets that are optional will instead be hidden from the UI. Consult the [Full Script Reference](/modding/p2ce-campaigns/script-reference#meta-keys) for information on which assets are optional, and art asset guidelines. - -![Selector & Fallback UI](images/campaign-minimum.webp) - -**All art assets must reside in the `.assets` subfolder in the respective addon. The game will not find the art assets if they are in another location.** - -# Example Campaign Files - -P2:CE ships with local addons to play Portal 2, Portal 1, and Half-Life 2 (including its episodes). These addons can be found [here](https://github.com/StrataSource/p2ce-addons/tree/feat/campaign-tests). - -# Campaign Progression - -Campaigns have their progression information saved inside `SAVE/campaign_save_data.kv3`. This file can be erased using the `campaign_savedata_reset` command. Campaign progression is currently tracked by chapter & map number. - -# Developing a Sourcemod? - -P2:CE and its menu system was designed as a gateway to sourcemods/standalone games. If a default campaign is specified (cvar: `campaign_default`), the game will use that campaign as the base menu state instead of the standard P2:CE menu. This can be helpful for mods that cannot or do not want to create a custom menu system (or simply as a starting platform while developing the mod). - -> [!NOTE] -> **There are extra considerations to take when developing a menu script that leverages the campaign system. Full details can be found on [the Technical Notes page](/modding/p2ce-campaigns/technical-notes).** diff --git a/docs/modding/p2ce-campaigns/gettings-started/00-getting-started.md b/docs/modding/p2ce-campaigns/gettings-started/00-getting-started.md new file mode 100644 index 00000000..1fa165ae --- /dev/null +++ b/docs/modding/p2ce-campaigns/gettings-started/00-getting-started.md @@ -0,0 +1,13 @@ +--- +title: "Getting Started" +weight: 0 +features: + - USE_CAMPAIGNMANAGER +--- + +# Getting Started +![Campaign Selection UI](../images/campaign-selection-screen.webp) + +P2:CE includes the ability for sourcemods, mappers, and addon authors to create custom campaigns. These custom campaigns can then be published to the Steam Workshop. A campaign refers to an organized bundle of maps, which could be tightly related (such as story-based campaigns) or have no relation at all (map/competition packs). + +P2:CE's campaign system is the primary form of user created playable content. Standalone maps are still available, but are folded into a "P2:CE Workshop" campaign as a playlist. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/gettings-started/01-creating-an-addon.md b/docs/modding/p2ce-campaigns/gettings-started/01-creating-an-addon.md new file mode 100644 index 00000000..e60fef32 --- /dev/null +++ b/docs/modding/p2ce-campaigns/gettings-started/01-creating-an-addon.md @@ -0,0 +1,23 @@ +--- +title: "01. Creating an Addon" +weight: 1 +features: + - USE_CAMPAIGNMANAGER +--- + +# Creating an Addon + +Campaigns in P2:CE are addons that ship with all required maps / custom resources and define a campaign. To create a new campaign focused addon, open the P2:CE SDK Launcher and create a new addon. + +| | | +|--------------------------------|---------------------------------------------| +| ![](./images/sdk-launcher.png) | ![](./images/sdk-launcher-create-addon.png) | + +Your addon will be created in the `addons` folder within the `p2ce` folder. On a default installation, the path would be `C:\Program Files (x86)\Steam\steamapps\common\Portal 2 Community Edition\p2ce\addons\yourmod`. + +![](./images/folder-addon.png) + +## Next steps +Now that we have created our addon, we can start setting up our campaign. + +Head over to [the campaign setup page](/modding/p2ce-campaigns/gettings-started/02-setting-up-your-campaign) to continue. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/gettings-started/02-setting-up-your-campaign.md b/docs/modding/p2ce-campaigns/gettings-started/02-setting-up-your-campaign.md new file mode 100644 index 00000000..c55e9bf3 --- /dev/null +++ b/docs/modding/p2ce-campaigns/gettings-started/02-setting-up-your-campaign.md @@ -0,0 +1,70 @@ +--- +title: "02. Setting up your campaign" +weight: 2 +features: + - USE_CAMPAIGNMANAGER +--- + +# Setting up your campaign +To create a campaign in your newly created addon, we need to create a `campaigns.kv3` file that holds all information about your campaign and references to the chapters, maps and additional metadata. Create a file named `campaigns.kv3` in the `scripts` folder of your addon. +Copy the following code into the file: + +> [!NOTE] +> An example of a functioning campaign script is available [here](https://github.com/StrataSource/p2ce-addons/blob/main/portal2/scripts/campaigns.kv3). + +``` +{ + meta = { + author = "John P2CE" + desc = "An example campaign" + full_logo = "logo.png" + } + "campaigns" = { + "yourcampaign" = { // "yourcampaign" is the ID of the campaign, it needs to be unique + title = "Your Campaign" + unlock_all = false + chapters = [ + { + title = "Your Chapter 1" + maps = [ + {name = "sp_a1_intro1" meta={ title="Container Ride" }}, + {name = "sp_a2_intro" meta={ title="Incinerator" }} + ] + }, + { + title = "Your Chapter 2" + maps = [ + {name = "sp_a2_laser_intro" meta={ title="Laser Intro" }}, + {name = "sp_a2_fizzler_intro" meta={ title="Fizzler Intro" }} + ] + } + ] + } + // You can add additional campaigns here + } +} +``` + +### Explaination +The campaigns file is split in two sections, the `meta` section and the `campaigns` section. The `meta` section holds information about the addon and the `campaigns` section holds general information about the campaign while the `chapters` section holds information about the chapters and maps. + +Each chapter is a list of maps and unlocks with the last map of the previous chapter played. The `unlock_all` property determines if all maps in the chapter are unlocked at the start of the chapter or if they are unlocked as the player completes the previous map. + +This `campaigns.kv3` file is a minimal example. There are lots of other properties that can be set and change how your campaign will be displayed in the game's campaigns menu. For more information, please refer to the [campaign.kv3 reference page](/modding/p2ce-campaigns/key-reference/00-general). + +## `.assets` folder +Inside your addons folder, you should create a folder named `.assets`. This folder enables you to store assets for the interface such as a logo, campaign icons or backgrounds. In our example, we've placed this placeholder logo in the `.assets` folder and referenced it in the `campaigns.kv3` file with the `full_logo` property. + +![](./images/logo.png) + +## Testing +Now that we have defined a campaign in our addon, we should test if it shows up in the game's campaign menu. +Open P2:CE and head to the Campaigns section. You should now see your newly created campaign and be able to start it. +It should look something like this: + +![](./images/ingame-menu.png) + +## Next steps +We've successfully created a campaign in our addon. Next up, we need to setup Hammer for an easier development experience. + +Head over to [the Hammer setup page](/modding/p2ce-campaigns/gettings-started/03-setup-hammer) to continue. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/gettings-started/03-setting-up-hammer.md b/docs/modding/p2ce-campaigns/gettings-started/03-setting-up-hammer.md new file mode 100644 index 00000000..d320e60e --- /dev/null +++ b/docs/modding/p2ce-campaigns/gettings-started/03-setting-up-hammer.md @@ -0,0 +1,46 @@ +--- +title: "03. Setting up Hammer" +weight: 3 +features: + - USE_CAMPAIGNMANAGER +--- + +# Setting up Hammer +Next up, we'll be setting up Hammer. While this step is not strictly necessary, it will teach you to setup a seamless workflow for editing your campaign. + +## Game Configuration +We want to create a new game configuration for our campaign. Open the SDK Launcher and Hammer. Next, go to the upper menu bar and open the Game Configurations through "Tools" → "Options" → "Game Configurations. + +Click on `Edit` to open the list of game configurations and create a duplicate of the `P2:CE` configuration. Close the game configuration dialog and select your newly created game configuration. + +Now we can make some changes to our game configuration. Make sure to create a folder named `mapssrc` in your addons folder for this step. + +Under the setting `Hammer VMF directory`, enter the path to your `mapssrc` folder. In a default installation, this path will be `C:\Program Files (x86)\Steam\steamapps\common\Portal 2 Community Edition\bin\win64\..\..\p2ce\addons\yourmod\mapssrc` where `yourmod` is your addons folder name. + +Under the setting `BSP final directory`, enter the path to your `maps` folder. In a default installation, this path will be `C:\Program Files (x86)\Steam\steamapps\common\Portal 2 Community Edition\bin\win64\..\..\p2ce\addons\yourmod\maps` where `yourmod` is your addons folder name. + +![Game Configurations](./images/hammer-game-config.png) + +> [!NOTE] +> Please restart Hammer after making these changes. You should see a dialog asking you to select a game configuration with your newly created configuration and `P2:CE` as options. + +## Run Configuration +For this next step, open the Addon Manager through Window → Addon Manager and enable the checkbox next to your addon. + +![](./images/hammer-addon-list.png) + +Create a small sample map in Hammer and click on the "Run Map" button at the top. If you don't see the expert modal, click on "Expert" at the bottom left. + +Add the following to your configuration that starts with `$game_exe` to automatically load your campaign when running the map: `-campaign "yourcampaign"`. + +> [!NOTE] +> You can also use the full identifier of your campaign `yourmod/yourcampaign` to prevent loading into the wrong campaign. + +![](./images/hammer-run-dialog.png) + +Now you should be able to run your map. After the compilation is finished, a game window should open with your custom campaign loaded. To check if you have loaded into the correct campaign, enter `campaign_info` in the console. + +## Next Steps +You have now fully set up your campaign addon and should be good to go. + +Head to [the campaigns.kv3 reference page](/modding/p2ce-campaigns/key-reference/00-general) to get more information about how to customize the interface of your campaign. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/folder-addon.png b/docs/modding/p2ce-campaigns/gettings-started/images/folder-addon.png new file mode 100644 index 00000000..5bb0d20c Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/folder-addon.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/hammer-addon-list.png b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-addon-list.png new file mode 100644 index 00000000..a78b3af0 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-addon-list.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/hammer-game-config.png b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-game-config.png new file mode 100644 index 00000000..6bb2cdc6 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-game-config.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/hammer-run-dialog.png b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-run-dialog.png new file mode 100644 index 00000000..e87dbfd7 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/hammer-run-dialog.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/ingame-menu.png b/docs/modding/p2ce-campaigns/gettings-started/images/ingame-menu.png new file mode 100644 index 00000000..ecb40b78 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/ingame-menu.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/logo.png b/docs/modding/p2ce-campaigns/gettings-started/images/logo.png new file mode 100644 index 00000000..9efeb783 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/logo.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher-create-addon.png b/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher-create-addon.png new file mode 100644 index 00000000..8361dc7e Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher-create-addon.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher.png b/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher.png new file mode 100644 index 00000000..96c3b710 Binary files /dev/null and b/docs/modding/p2ce-campaigns/gettings-started/images/sdk-launcher.png differ diff --git a/docs/modding/p2ce-campaigns/gettings-started/meta.json b/docs/modding/p2ce-campaigns/gettings-started/meta.json new file mode 100644 index 00000000..1aa3d4f7 --- /dev/null +++ b/docs/modding/p2ce-campaigns/gettings-started/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Getting Started", + "weight": 0 +} diff --git a/docs/modding/p2ce-campaigns/key-reference/00-general.md b/docs/modding/p2ce-campaigns/key-reference/00-general.md new file mode 100644 index 00000000..e848ed87 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/00-general.md @@ -0,0 +1,22 @@ +--- +title: "General Information" +weight: 0 +features: + - USE_CAMPAIGNMANAGER +--- +# General Information +These pages function as a documentation for the various fields in the P2:CE campaigns. + +- [Keys for Campaigns](/modding/p2ce-campaigns/key-reference/01-campaign-keys) +- [Keys for Chapters](/modding/p2ce-campaigns/key-reference/02-chapter-keys) +- [Keys for Maps](/modding/p2ce-campaigns/key-reference/03-map-keys) + +There are also [meta keys](/modding/p2ce-campaigns/key-reference/meta-keys) specifically for the P2:CE default interface. + +> [!TIP] +> **SEE ALSO:** [Example implementations for Portal 1, Portal 2 & Half-Life 2](https://github.com/StrataSource/p2ce-addons/tree/feat/campaign-tests) + +## Overrides +Properties can be overridden for each level (Campaign, Chapter, Map). For example, defining the `background_image` property in both the **Campaign** and **Chapter** block will set the background image to the one defined in the **Chapter** block if the player is currently in that chapter. + +This way your campaign can have a customized interface for each chapter. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/01-campaign-keys.md b/docs/modding/p2ce-campaigns/key-reference/01-campaign-keys.md new file mode 100644 index 00000000..618ded9f --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/01-campaign-keys.md @@ -0,0 +1,14 @@ +--- +title: "Keys for Campaigns" +weight: 1 +features: + - USE_CAMPAIGNMANAGER +--- +# Keys for Campaigns + +| Key | Type | Details | Optional | +|--------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| `title` | string | This is the name of the campaign. If a translation key is provided, it will be localized. | No | +| `unlock_all` | boolean | Determines if all chapters are unlocked and no unlock state should be tracked. (This is set to `false` by default) | Yes | +| `meta` | block | [Meta keys](/modding/p2ce-campaigns/key-reference/meta-keys) for the P2:CE interface. These values apply to all chapters/maps unless overridden. | Yes | +| `chapters` | array | Array of chapters. | No | \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/02-chapter-keys.md b/docs/modding/p2ce-campaigns/key-reference/02-chapter-keys.md new file mode 100644 index 00000000..185c8783 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/02-chapter-keys.md @@ -0,0 +1,14 @@ +--- +title: "Keys for Chapters" +weight: 2 +features: + - USE_CAMPAIGNMANAGER +--- +# Keys for Chapters + +| Key | Type | Details | Optional | +|----------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------|----------| +| `title` | string | This is the name of the chapter. If a translation key is provided, it will be localized. | No | +| `save_comment` | string | A string that will be appended to the save file. [More information](/modding/p2ce-campaigns/campaign-progression) | Yes | +| `meta` | block | [Meta keys](/modding/p2ce-campaigns/key-reference/meta-keys) for the P2:CE interface. These values apply to all maps unless overridden. | Yes | +| `maps` | array | Array of maps. | No | \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/03-map-keys.md b/docs/modding/p2ce-campaigns/key-reference/03-map-keys.md new file mode 100644 index 00000000..d3d3fa52 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/03-map-keys.md @@ -0,0 +1,27 @@ +--- +title: "Keys for Maps" +weight: 3 +features: + - USE_CAMPAIGNMANAGER +--- +# Keys for Maps +| Key | Type | Details | Optional | +|--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| `name` | string | The map filename, without the `.bsp` extension. | No | +| `meta` | block | [Meta keys](/modding/p2ce-campaigns/key-reference/meta-keys) for the P2:CE interface. There are special *map meta keys* that are only available on this level. | Yes | + +## Map meta keys +> [!NOTE] +> These meta keys are only available for maps. + +### `title` + +An optional meta key that sets the map title. If not set, the `bsp` file name will be used. This string is used for the map selector interface. + +![Map Selector](../images/map-selector.webp) + +### `img` + +An optional path to an image. If at least one map in a chapter has this key set, it will display the map selector in a grid view. + +![Map Selector](../images/map-thumbs.webp) \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/00-meta-keys.md b/docs/modding/p2ce-campaigns/key-reference/meta-keys/00-meta-keys.md new file mode 100644 index 00000000..2f2f24a0 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/00-meta-keys.md @@ -0,0 +1,15 @@ +--- +title: "Meta Keys" +weight: 0 +features: + - USE_CAMPAIGNMANAGER +--- + +# Meta Keys + +> [!WARNING] +> Meta level keys are unique to P2:CE's menu implementation. Changing the UI scripts will lose what these keys provide, unless they are reimplemented. See P2:CE's [Panorama code](https://github.com/StrataSource/p2ce-panorama-ui) to see how these meta keys are implemented, and see the [Technical Details](/modding/p2ce-campaigns/technical-notes) page for more information. + +Meta keys are additional properties that change the design and branding of the interface for your campaign. + +All art assets must reside in the `.assets` subfolder in the respective addon. The game will not find the art assets if they are in another location. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/01-campaign-selector.md b/docs/modding/p2ce-campaigns/key-reference/meta-keys/01-campaign-selector.md new file mode 100644 index 00000000..ae793a22 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/01-campaign-selector.md @@ -0,0 +1,45 @@ +--- +title: "Campaign Selector" +weight: 1 +features: + - USE_CAMPAIGNMANAGER +--- + +# Campaign Selector + +> [!NOTE] +> All meta keys are strings. Asset paths are relative to the addons `.assets` directory. + +![Campaign Button Legend](../../images/campaign-button-legend.webp) + +## [1] `selector_cover` +This is the primary cover image. A placeholder will be displayed if no image is specified. + +**Recommended Size:** 920x430 (or aspect ratio equivalent) + +## [2] `author` +This is the name to display in the campaign selector, which will get localized if provided a token. + +If no author is specified, the author defined in the ``addon.kv3`` will be used. If no other is specified in the ``addon.kv3``, the author will be hidden from the UI. + +## [3] `description` / `desc` +This is the description to display in the campaign selector, which will get localized if provided a token. + +If no description is specified, the description will be hidden from the UI. + +## [4] `selector_button_background` +A path to an asset in the addons `.assets` folder. This is the background image for the campaign selector button. A placeholder will be displayed if no image is specified. + +**Recommended Size:** 1920x620 (or aspect ratio equivalent) + +This image will be sized to cover a region of the button. Upper and lower portions may be clipped. Important elements should be as close to the center vertically as much as possible. + +![Selector Button Background Guideline](../../images/button-guideline.png) + +## ``boxart`` +![Boxart Example](../../images/campaign-boxart.webp) +A path to an asset in the addons `.assets` folder. This is the boxart image for the campaign selector. It will be displayed to the right of the campaign list. + +**Recommended Size:** 600x900 (or aspect ratio equivalent) + +This image will be sized to fit this aspect ratio. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/02-main-menu.md b/docs/modding/p2ce-campaigns/key-reference/meta-keys/02-main-menu.md new file mode 100644 index 00000000..647b7f7b --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/02-main-menu.md @@ -0,0 +1,61 @@ +--- +title: Main Menu +weight: 2 +features: + - USE_CAMPAIGNMANAGER +--- + +# Main Menu + +> [!NOTE] +> All meta keys are strings. Asset paths are relative to the addons `.assets` directory. + +## Logos +### `square_logo` + +| | | +|--------------------------------------------------|-----------------------------------------------| +| ![Logo Example](../../images/campaign-logo.webp) | ![Spinner Example](../../images/spinner.webp) | + +A path to an asset in the addons `.assets` folder. The square logo will be displayed in the main menu to the right of the full_logo if the player hovers over the *Resume* menu item. it is also displayed inside the loading spinner. + +**Recommended Size:** 256x256 (or aspect ratio equivalent) + +**Recommended Format:** svg (As they scale nicely to any display size) + +### `full_logo` + +![Full Logo Example](../../images/campaign-full-logo.webp) + +A path to an asset in the addons `.assets` folder. The full logo will be displayed on the main menu and in the pause menu. If not set, no logo will be displayed. + +This image will be sized to fit on the main menu. Any resolution/ratio can be used and should appear fine. Currently, the full logo will be constrained to center fit inside a 540x130 pixel frame. + +**Recommended Format:** svg (As they scale nicely to any display size) + +### `full_logo_size_preset` +Used to change the display of `full_logo`. Defaults to `standard`. + +| Value | Description | +|------------|--------------------| +| `standard` | Standard display | +| `large` | Larger display | + +## Background +### `background_map` +A map name to use for the background. If it is not set or the player has disabled background map loading, `background_movie` (and after that) `background_image` are used as fallbacks. + +### `background_movie` +A path to an asset in the addons `.assets` folder. The video will be displayed as the background. If it is not set, `background_image` is used as fallback. + +**Recommended Size**: 1920x1080 (or aspect ratio equivalent) + +### `background_image` +A path to an asset in the addons `.assets` folder. The image will be displayed as the background if `background_movie` or `background_map` are not set. If not set, a fallback image will be used. + +**Recommended Size**: 1920x1080 (or aspect ratio equivalent) + +### `background_music` +This key's value is **not** a path to a raw asset file. Instead, it must be set to a valid soundscript entry. + +This image will be sized to cover the entire screen as the background. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/03-chapter-selector.md b/docs/modding/p2ce-campaigns/key-reference/meta-keys/03-chapter-selector.md new file mode 100644 index 00000000..fc3d9196 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/03-chapter-selector.md @@ -0,0 +1,39 @@ +--- +title: Chapter Selector +weight: 3 +features: + - USE_CAMPAIGNMANAGER +--- + +# Chapter Selector + +> [!NOTE] +> All meta keys are strings. Asset paths are relative to the addons `.assets` directory. + +## `locked_title` +Locked chapters can be assigned their own title when they are locked. By default they will appear as "????" + +## `chapter_display_mode` + +![Chapter Modes Display](../../images/chapter-modes.webp) + +Defines the display mode of the chapter selector. The default display mode is `list`. + +| Value | Description | +|-----------|-----------------------------------------------------------------------------------------------------------| +| `classic` | Traditional Half-Life 2/Portal 1 film strip with 3 chapters displayed per page | +| `super` | Simiar to `classic` but displaying a single chapter per page | +| `list` | Displays a list of all chapters on the left side with a detail view of the selected chapter on the right. | +| `grid` | Displays chapters as a 3 column grid. Ideal for map packs. | + +## `thumbnail` + +![Saves List](../../images/saves-list.webp) + +A path to an asset in the addons `.assets` folder. This thumbnail is not only used in the chapter selector but also appears as a background in the save menu. If no image is specified, a fallback will be used. + +**Recommended Size:** 1920x1080 (or aspect ratio equivalent) + +This image will be sized to fit for chapter selection entries. However, in the saves menu, this image will be sized to cover a region of the save button, so some parts of the thumbnail will be cropped. + +![Saves List Guideline](../../images/save-image-guideline.png) \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/04-loading-screen.md b/docs/modding/p2ce-campaigns/key-reference/meta-keys/04-loading-screen.md new file mode 100644 index 00000000..1811ea76 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/04-loading-screen.md @@ -0,0 +1,49 @@ +--- +title: Loading Screen +weight: 4 +features: + - USE_CAMPAIGNMANAGER +--- + +# Loading Screen + +> [!NOTE] +> All meta keys are strings. Asset paths are relative to the addons `.assets` directory. + +## `loading_square_logo_padding` +The amount of padding given to the loading icon in the corner. If not specified, no padding will be applied. + +While this is a string, the value given must be a whole non-negative number. + +## `loading_screen` +A path to an asset in the addons `.assets` folder. This image will be used when the player is loading into a map from the main menu. If not specified, a black screen will be shown. + +**Recommended Size:** 1920x1080 (or aspect ratio equivalent) + +This image will be sized to cover the entire screen as the background. + +## `transition_screen` +A path to an asset in the addons `.assets` folder. This image will be used when the player is loading into a map from a previous map. If not specified, a black screen will be shown. + +**Recommended Size:** 1920x1080 (or aspect ratio equivalent) + +This image will be sized to cover the entire screen as the background. + +## Loading/Transition Screen fading + +| | | +|---------------------------------------------------|---------------------------------------------------| +| ![Loading Example 1](../../images/loading_a.webp) | ![Loading Example 2](../../images/loading_b.webp) | + +As with the loading screen used in Portal 2, P2:CE's loading screen is layouted with overlayed images that are fading in/out based on the loading progress. Additionally, P2:CE differentiates between loading into a map from the main menu and transitioning into a map from a previous map. + +The loading screen of P2:CE supports two images with a fade happening at 50%. To fade between two images, an index will be added to the asset path. + +### Example +``` +meta = { + loading_screen="loading_screen.png" +} +``` + +With this, the loading screen will fade between `[ADDON PATH]/.assets/loading_screen_1.png` and `[ADDON PATH]/.assets/loading_screen_2.png`. \ No newline at end of file diff --git a/docs/modding/p2ce-campaigns/key-reference/meta-keys/meta.json b/docs/modding/p2ce-campaigns/key-reference/meta-keys/meta.json new file mode 100644 index 00000000..0e144460 --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta-keys/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Meta Keys", + "weight": 4 +} diff --git a/docs/modding/p2ce-campaigns/key-reference/meta.json b/docs/modding/p2ce-campaigns/key-reference/meta.json new file mode 100644 index 00000000..d8f9b58d --- /dev/null +++ b/docs/modding/p2ce-campaigns/key-reference/meta.json @@ -0,0 +1,4 @@ +{ + "title": "campaigns.kv3 Reference", + "weight": 1 +} diff --git a/docs/modding/p2ce-campaigns/meta.json b/docs/modding/p2ce-campaigns/meta.json index bf40ae42..3d975394 100644 --- a/docs/modding/p2ce-campaigns/meta.json +++ b/docs/modding/p2ce-campaigns/meta.json @@ -1,4 +1,4 @@ { "title": "P2:CE Campaigns", - "weight": 40 + "weight": 1 } diff --git a/docs/modding/p2ce-campaigns/script-reference.md b/docs/modding/p2ce-campaigns/script-reference.md deleted file mode 100644 index b5a83fa0..00000000 --- a/docs/modding/p2ce-campaigns/script-reference.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -title: Full Script Reference -features: - - USE_CAMPAIGNMANAGER ---- - -# Full Campaign Script Reference - -> [!TIP] -> **SEE ALSO:** [Bundled Campaign Scripts for Portal 1, Portal 2 & Half-Life 2](https://github.com/StrataSource/p2ce-addons/tree/feat/campaign-tests) - -# Setup -Script must exist in `scripts/campaigns.kv3` to be loaded. The file's format is KeyValues 3. This file contains a root block that then has an optional `"meta"` block, and a required `"campaigns"` block, in which every campaign will live, using a string as the ID. - -# Ideal Meta Locations - -The following is a baseline snippet of ideal meta key locations. Note that keys pointing to asset paths should be filled in and the existence of these will result in placeholder assets being used instead. -``` -{ - meta = { - author = "Author" - } - campaigns = { - "campaign_1" = { - title = "Campaign 1 Title" - unlock_all = false - meta = { - desc = "Campaign 1 Description" - box_art = "" - selector_cover = "" - selector_button_background = "" - square_logo = "" - full_logo = "" - full_logo_size_preset = "" - chapter_display_mode = "list" - loading_square_logo_padding = "0" - } - chapters = [ - // copy the below block for every chapter that should be a part of this campaign - { - title = "Campaign 1 Chapter 1 Title" - save_comment = "" - maps = [ - // copy the below line for every map that should belong in this chapter - {name="campaign_1_map" meta={ title="Map 1 Title" img="" }}, - ] - meta = { - thumbnail = "" - background_map = "" - background_movie = "" - background_music = "" - loading_screen = "" - transition_screen = "" - locked_title = "" - } - } - ] - } - } -} -``` - -# Campaign Level Keys - -| Key | Type | Details | -| --- | ---- | ------- | -| `title` | string | Human readable string that will be localized if a token is provided. This is the name of the campaign. | -| `unlock_all` | boolean | (OPTIONAL, DEFAULT: FALSE) Determines if all chapters are unlocked and no unlock state should be tracked.| -| `meta` | block | (OPTIONAL) Block that describes art/background assets to P2:CE's menus. These values apply to all chapters/maps unless overridden. | -| `chapters` | array | Array of chapter blocks. | - -# Chapter Level Keys - -| Key | Type | Details | -| --- | ---- | ------- | -| `title` | string | Human readable string that will be localized if a token is provided. This is the name of the chapter. | -| `save_comment` | string | (OPTIONAL) Appended string to save files. | -| `meta` | block | (OPTIONAL) Overrides fields in the campaign's meta block. These values apply to all maps unless overridden. | -| `maps` | array | Array of chapter blocks. | - -# Map Level Keys - -| Key | Type | Details | -| --- | ---- | ------- | -| `name` | string | The map filename, without the `.bsp` extension. | -| `meta` | block | (OPTIONAL) Override values in the chapter and campaign `meta` blocks. [This block has unique keys.](#maps) | - -# Meta Keys - -> [!WARNING] -> Meta level keys are unique to P2:CE's menu implementation. Changing the UI scripts will lose what these keys provide, unless they are reimplemented. See P2:CE's [Panorama code](https://github.com/StrataSource/p2ce-panorama-ui) to see how these meta keys are implemented, and see the [Technical Details](/modding/p2ce-campaigns/technical-notes) page for more information. - -Most meta keys define art assets which are used in various locations/stretch to certain sizes. Some detail may be cropped. If you use non-standard ratios or something the UI is not expecting, it may not display properly. - -Optional keys are marked **(OPTIONAL)**. In the absence of this tag, it is either strongly recommended or required (and would result in a fallback image being used). - -**All art assets must reside in the `.assets` subfolder in the respective addon. The game will not find the art assets if they are in another location.** - -> [!WARNING] -> **ALL META KEYS ARE STRINGS, NO EXCEPTIONS.** - -## Campaign Selector - -> [!NOTE] -> Some of these assets and their specifications are derived from the [Steamworks Partner game asset requirements](https://partner.steamgames.com/doc/store/assets/libraryassets). These requirements were chosen to allow campaign authors to easily migrate their work to a standalone Steam mod at any time if they so choose. - -![Campaign Button Legend](images/campaign-button-legend.webp) - -### (1) `selector_cover` - -Recommended resolution: 920x430 (or aspect ratio equivalent) - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -### (2) `author` - -**(OPTIONAL)** - -The name to display in the campaign selector, which will get localized if provided a token. This will override the addon author, if it can be retrieved. If no author is specified and it cannot be retrieved, it will be hidden from the UI. - -### (3) `desc` - -**(OPTIONAL)** - -Optional description to display in the campaign selector, which will get localized if provided a token. - -### (4) `selector_button_background` - -**(OPTIONAL)** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Resolution: 1920x620 (or aspect ratio equivalent) - -This image will be sized to cover a region of the button. Upper and lower portions may be clipped. Important elements should be as close to the center vertically as much as possible. - -![Selector Button Background Guideline](images/button-guideline.png) - -### `box_art` - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Resolution: 600x900 (or aspect ratio equivalent) - -This image will be sized to fit this aspect ratio. - -![Boxart Example](images/campaign-boxart.webp) - -## Menu - -### `square_logo` - -**(OPTIONAL)** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Recommended resolution: 256x256 (or aspect ratio equivalent) - -`.svg` file format recommended. All official logos are provided in this format. - -Used in loading screen and main menu. - -This logo is used in the main menu and appears when the user hovers over the resume button. If this image is not an `.svg`, it will not appear. - -This sample has the logo as Bendy, appearing behind the menu. -![Logo Example](images/campaign-logo.webp) - -![Spinner Example](images/spinner.webp) - -### `background_map` - -The background map to load into while on the menu when the player has progressed into the point where this field is defined (usually a chapter block). This normally takes priority over `background_movie` or `background_image`. If the user has disabled background map loading, `background_movie` or `background_image` is used as a fallback. - -### `background_movie` - -Path to the video to use, including the file extension. - -Resolution: 1920x1080 (or aspect ratio equivalent) - -The movie to play on the menu when the player has progressed into the point where this field is defined (usually a chapter block). This takes priority over `background_image`. - -### `background_image` - -> [!NOTE] -> **This field is the final resort. If none of the prior `background_` asset fields are specified and this asset does not exist or fails to load, a fallback image will be used instead.** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Resolution: 1920x1080 (or aspect ratio equivalent) - -The image to display on the menu when the player has progressed into the point where this field is defined (usually a chapter block). - -This image will be sized to cover the entire screen as the background. - -### `background_music` - -**(OPTIONAL)** - -The music to play on the menu. This must be a soundscript entry and **cannot** be a raw sound reference. If this field is specified, it will play regardless of which `background_` asset is used on the menu. - -### `full_logo` - -**(OPTIONAL, HIDES LOGO IF NOT SPECIFIED)** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Also used in main menu. - -This image will be sized to fit on the main menu. Any resolution/ratio can be used and should appear fine. Currently, the full logo will be constrained to center fit inside a 540x130 pixel frame. - -All official logos are provided in `.svg` format. - -![Full Logo Example](images/campaign-full-logo.webp) - -### `full_logo_size_preset` - -**(OPTIONAL, DEFAULT: "STANDARD")** - -Allows for making the image specified in `full_logo` a different size than the default. - -Valid values are: -- `standard` (default) -- `large` (makes image specified larger) - -## Chapter Selection - -### `locked_title` - -**(OPTIONAL, DEFAULT: "????")** - -Locked chapters can be assigned their own title when they are locked. By default they will appear as "????" but with `locked_title` it can be changed. - -### `chapter_display_mode` - -**(OPTIONAL, DEFAULT: "LIST")** - -![Chapter Modes Display](images/chapter-modes.webp) - -The display mode when the player enters the chapter selection screen. - -Valid values are: -- `classic` (traditional VGUI film strip with 3 chapters displayed per page) -- `super` (singular massive tile) -- `list` (default) -- `grid` (ideal for map packs) - -### `thumbnail` - -Resolution: 1920x1080 (or aspect ratio equivalent) - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Chapter thumbnail predominantly used in the chapter selection screen, but also appears in the saves menu. - -This image will be sized to fit for chapter selection entries. However, in the saves menu, this image will be sized to cover a region of the save button. Some parts of the image may be clipped in that regard. - -![Saves List](images/saves-list.webp) - -![Saves List Guideline](images/save-image-guideline.png) - -## Loading Screens - -### `loading_screen` - -**(OPTIONAL, DEFAULTS TO BLACK SCREEN IF NOT SPECIFIED)** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Resolution: 1920x1080 (or aspect ratio equivalent) - -The image to use when the player is loading into a map from the main menu. - -This image will be sized to cover the entire screen as the background. - -### `transition_screen` - -**(OPTIONAL, DEFAULTS TO BLACK SCREEN IF NOT SPECIFIED)** - -Path to the image to use, including the file extension. This path is relative to the addon's `.assets` directory. - -Resolution: 1920x1080 (or aspect ratio equivalent) - -The image to use when the player is transitioning to a map from a previous one. - -This image will be sized to cover the entire screen as the background. - -### Loading/Transition Screen Considerations -> [!WARNING] -> **PLEASE READ THE FOLLOWING SECTION CAREFULLY.** - -P2:CE's loading screen is derived from Portal 2's where there are multiple images faded on top of each other based on loading progress. Additionally, it has two different loading screens, one for loading into a map from the menu (`loading_screen`), and another for transitioning between maps (`transition_screen`). In P2:CE specifically, the number of assets to provide is two, and the second image is faded in after the loading progress exceeds 50%. To facilitate this, `loading_screen` and `transition_screen` paths are treated specially. - -The campaign script specifies the asset name prefix and image extension, while the UI script adds a numeric suffix to the information provided. If a field is not specified, the background will be a solid black color. If a field is specified and the second asset the UI searches for does not exist, a fallback image will be used. - -![Loading Example 1](images/loading_a.webp) -![Loading Example 2](images/loading_b.webp) - -**Example:** - -Suppose that loading screen assets are defined as such within a meta block: -``` -meta = { - loading_screen="loading_screen.png" - transition_screen="transition_screen.png" -} -``` - -In the UI, these would then be translated into: -``` -loading_screens = [ - "[ADDON PATH]/.assets/loading_screen_1.png", - "[ADDON PATH]/.assets/loading_screen_2.png" -] -transition_screens = [ - "[ADDON PATH]/.assets/transition_screen_1.png", - "[ADDON PATH]/.assets/transition_screen_2.png" -] -``` -**(Note that this does not represent the actual campaign information as laid out in memory or by the campaign system, this is an example for human readability)** - -### `loading_square_logo_padding` - -**(OPTIONAL, APPLIES NO PADDING IF NOT SPECIFIED)** - -The padding to give to the logo in the spinner that appears in the loading screen to help fit it inside better. This is used for Half-Life 2's campaign script. - -While this is a string, the value given must be a whole non-negative number. - -## Maps - -> [!NOTE] -> The following keys are for meta blocks within a map block. These keys are not used anywhere else. -> -> ``` -> maps = [ -> { name = "cool_map" meta = { title = "My Awesome Map", img = "cool_map.png" } } -> ] -> ``` - -### `title` - -**(OPTIONAL)** - -Human-readable name for this map, used in the map selector. If not specified, the map selector will use the map's name. - -![Map Selector](images/map-selector.webp) - -### `img` - -**(OPTIONAL)** - -Map thumbnail asset path, used in the map selector. If this field is not specified in *any* map in the current chapter block, the asset will not appear. If there is at least one `img` field specified, the map selector turns into a grid layout and displays images for all maps (even if a map does not define one). - -![Map Selector](images/map-thumbs.webp) diff --git a/docs/modding/p2ce-campaigns/source-mods.md b/docs/modding/p2ce-campaigns/source-mods.md new file mode 100644 index 00000000..b54114c1 --- /dev/null +++ b/docs/modding/p2ce-campaigns/source-mods.md @@ -0,0 +1,12 @@ +--- +title: Source Mods +features: + - USE_CAMPAIGNMANAGER +weight: 90 +--- + +# Source Mods +P2:CE and its menu system was designed as a gateway to sourcemods/standalone games. If a default campaign is specified (cvar: `campaign_default`), the game will use that campaign as the base menu state instead of the standard P2:CE menu. This can be helpful for mods that cannot or do not want to create a custom menu system (or simply as a starting platform while developing the mod). + +> [!NOTE] +> **There are extra considerations to take when developing a menu script that leverages the campaign system. Full details can be found on [the Technical Notes page](/modding/p2ce-campaigns/advanced/technical-notes).**