Saving Princess: implement new game (#3238)

* Saving Princess: initial commit * settings -> options Co-authored-by: Scipio Wright <scipiowright@gmail.com> * settings -> options Co-authored-by: Scipio Wright <scipiowright@gmail.com> * replace RegionData class with List[str] RegionData was only wrapping a List[str], so we can directly use List[str] * world: MultiWorld -> multiworld: MultiWorld * use world's random instead of multiworld's * use state's has_any and has_all where applicable * remove unused StartInventory import * reorder PerGameCommonOptions * fix relative AutoWorld import Co-authored-by: Scipio Wright <scipiowright@gmail.com> * clean up double spaces * local commands -> Local Commands Co-authored-by: Nicholas Saylor <79181893+nicholassaylor@users.noreply.github.com> * remove redundant which items section Co-authored-by: Nicholas Saylor <79181893+nicholassaylor@users.noreply.github.com> * game info rework * clean up item count redundancy * add game to readme and codeowners * fix get_region_entrance return type * world.multiworld.get -> world.get * add more events added events for the boss kills that open the gate, as well as for system power being restored these only apply if expanded pool is not selected * add client/autoupdater to launcher * reorder commands in game info * update docs with automated installation info * add quick links to doc * Update setup_en.md * remove standalone saving princess client * doc fixes * code improvements and redundant default removal as suggested by @Exempt-Medic this includes the removal of events from the item/location name to id, as well as checking for the player name being ASCII * add option to change launch coammnd the LaunchCommand option is filled to either the executable or wine with the necessary arguments based on Utils.is_windows * simplify valid install check * mod installer improvements now deletes possible existing files before installing the mod * add option groups and presets * add required client version * update docs about cheat items pop-ups items sent directly by the server (such as with starting inventory) now have pop-ups just like any other item * add Steam Input issue to faq * Saving Princess: BRAINOS requires all weapons * Saving Princess: Download dll and patch together Previously, gm-apclientpp.dll was downloaded from its own repo With this update, the dll is instead extracted from the same zip as the game's patch * Saving Princess: Add URI launch support * Saving Princess: goal also requires all weapons given it's past brainos * Saving Princess: update docs automatic connection support was added, docs now reflect this * Saving Princess: extend([item]) -> append(item) * Saving Princess: automatic connection validation also parses the slot, password and host:port into parameters for the game * Saving Princess: change subprocess .run to .Popen This keeps the game from freezing the launcher while it is running --------- Co-authored-by: Scipio Wright <scipiowright@gmail.com> Co-authored-by: Nicholas Saylor <79181893+nicholassaylor@users.noreply.github.com> Co-authored-by: NewSoupVi <57900059+NewSoupVi@users.noreply.github.com>
2025-10-21 20:21:32 -06:00 · 2024-12-07 11:29:27 +01:00
parent ced93022b6
commit c9625e1b35
12 changed files with 1341 additions and 0 deletions
--- a/worlds/saving_princess/docs/en_Saving
+++ b/worlds/saving_princess/docs/en_Saving
@@ -0,0 +1,55 @@
+# Saving Princess
+
+## Quick Links
+- [Setup Guide](/tutorial/Saving%20Princess/setup/en)
+- [Options Page](/games/Saving%20Princess/player-options)
+- [Saving Princess Archipelago GitHub](https://github.com/LeonarthCG/saving-princess-archipelago)
+
+## What changes have been made?
+
+The game has had several changes made to add new features and prevent issues. The most important changes are the following:
+- There is an in-game connection settings menu, autotracker and client console.
+- New save files are created and used automatically for each seed and slot played.
+- The game window can now be dragged and a new integer scaling option has been added.
+
+## What items and locations get shuffled?
+
+The chest contents and special weapons are the items and locations that get shuffled.
+
+Additionally, there are new items to work as filler and traps, ranging from a full health and ammo restore to spawning a Ninja on top of you.
+
+The Expanded Pool option, which is enabled by default, adds a few more items and locations:
+- Completing the intro sequence, powering the generator with the Volt Laser and defeating each boss become locations.
+- 4 Keys will be shuffled, which serve to open the door to the final area in place of defeating the main area bosses.
+- A System Power item will be shuffled, which restores power to the final area instead of this happening when the generator is powered.
+
+## What does another world's item look like in Saving Princess?
+
+Some locations, such as boss kills, have no visual representation, but those that do will have the Archipelago icon.
+
+Once the item is picked up, a textbox will inform you of the item that was found as well as the player that will be receiving it.
+
+These textboxes will have colored backgrounds and comments about the item category.
+For example, progression items will have a purple background and say "Looks plenty important!".
+
+## When the player receives an item, what happens?
+
+When you receive an item, a textbox will show up.
+This textbox shows both which item you got and which player sent it to you.
+
+If you send an item to yourself, however, the sending player will be omitted.
+
+## Unique Local Commands
+
+The following commands are only available when using the in-game console in Saving Princess:
+- `/help` Returns the help listing.
+- `/options` Lists currently applied options.
+- `/resync` Manually triggers a resync. This also resends all found locations.
+- `/unstuck` Sets save point to the first save point. Portia is then killed.
+- `/deathlink [on|off]` Toggles or sets death link mode.
+- `/instantsaving [on|off]` Toggles or sets instant saving.
+- `/sprint {never|always|jacket}` Sets sprint mode.
+- `/cliff {never|always|vanilla}` Sets Cliff's weapon upgrade condition.
+- `/ace {never|always|vanilla}` Sets Ace's weapon upgrade condition.
+- `/iframes n` Sets the iframe duration % multiplier to n, where 0 <= n <= 400.
+- `/shake n` Sets the shake intensity % multiplier to n, where 0 <= n <= 100.
--- a/worlds/saving_princess/docs/setup_en.md
+++ b/worlds/saving_princess/docs/setup_en.md
@@ -0,0 +1,148 @@
+# Saving Princess Setup Guide
+
+## Quick Links
+- [Game Info](/games/Saving%20Princess/info/en)
+- [Options Page](/games/Saving%20Princess/player-options)
+- [Saving Princess Archipelago GitHub](https://github.com/LeonarthCG/saving-princess-archipelago)
+
+## Installation Procedures
+
+### Automated Installation
+
+*These instructions have only been tested on Windows and Ubuntu.*
+
+Once everything is set up, it is recommended to continue launching the game through this method, as it will check for any updates to the mod and automatically apply them.
+This is also the method used by the Automatic Connection described further below.
+
+1. Purchase and download [Saving Princess](https://brainos.itch.io/savingprincess)
+2. Download and install the latest [Archipelago release](https://github.com/ArchipelagoMW/Archipelago/releases/latest)
+3. Launch `ArchipelagoLauncher` and click on "Saving Princess Client"
+   * You will probably need to scroll down on the Clients column to see it
+4. Follow the prompts
+   * On Linux, you will need one of either Wine or 7z for the automated installation
+
+When launching the game, Windows machines will simply run the executable. For any other OS, the launcher defaults to trying to run the game through Wine. You can change this by modifying the `launch_command` in `options.yaml` or `host.yaml`, under the `saving_princess_settings` section.
+
+### Manual Windows Installation
+
+Required software:
+- Saving Princess, found at its [itch.io Store Page](https://brainos.itch.io/savingprincess)
+- `saving_princess_basepatch.bsdiff4` and `gm-apclientpp.dll`, from [saving_princess_archipelago.zip](https://github.com/LeonarthCG/saving-princess-archipelago/releases/latest)
+- Software that can decompress the previous files, such as [7-zip](https://www.7-zip.org/download.html)
+- A way to apply `.bsdiff4` patches, such as [bspatch](https://www.romhacking.net/utilities/929/)
+
+Steps:
+1. Extract all files from `Saving Princess.exe`, as if it were a `.7z` file
+   * Feel free to rename `Saving Princess.exe` to `Saving Princess.exe.7z` if needed
+   * If installed through the itch app, you can find the installation directory from the game's page, pressing the cog button, then "Manage" and finally "Open folder in explorer"
+2. Extract all files from `saving_princess_archipelago.zip` into the same directory as the files extracted in the previous step
+   * This should include, at least, `saving_princess_basepatch.bsdiff4` and `gm-apclientpp.dll`
+3. If you don't have `original_data.win`, copy `data.win` and rename its copy to `original_data.win`
+   * By keeping an unmodified copy of `data.win`, you will have an easier time updating in the future
+4. Apply the `saving_princess_basepatch.bsdiff4` patch using your patching software
+5. To launch the game, run `Saving Princess v0_8.exe`
+
+### Manual Linux Installation
+
+*These instructions have only been tested on Ubuntu.*
+
+The game does run mostly well through Wine, so it is possible to play on Linux, although there are some minor sprite displacement and sound issues from time to time.
+
+You can follow the instructions for Windows with very few changes:
+
+* Using the `p7zip-full` package to decompress the file.
+```
+7z e 'Saving Princess.exe'
+```
+* And the `bsdiff` package for patching.
+```
+bspatch original_data.win data.win saving_princess_basepatch.bsdiff4
+```
+
+## Configuring your YAML file
+
+### What is a YAML file and why do I need one?
+
+See the guide on setting up a basic YAML at the Archipelago setup
+guide: [Basic Multiworld Setup Guide](/tutorial/Archipelago/setup/en).
+
+### Where do I get a YAML file?
+
+You can customize your options by visiting the [Saving Princess Player Options Page](/games/Saving%20Princess/player-options).
+
+### Verifying your YAML file
+
+If you would like to validate your config file to make sure it works, you may do so on the YAML Validator page. YAML
+validator page: [YAML Validation page](/check).
+
+## Joining a MultiWorld Game
+
+### Automatic Connection on archipelago.gg
+
+1. Go to the room page of the MultiWorld you are going to join.
+2. Click on your slot name on the left side.
+3. Click the "Saving Princess Client" button in the prompt.
+   * This launches the same client described in the Automated Installation section.
+4. Upon reaching the title screen, a connection attempt will automatically be started.
+
+Note that this updates your Saving Princess saved connection details, which are described in the Manual Connection section.
+
+### Manual Connection
+
+After launching the game, enter the Archipelago options menu through the in-game button with the Archipelago icon.
+From here, enter the different menus and type in the following details in their respective fields:
+- **server:port** (e.g. `archipelago.gg:38281`)
+   * If hosting on the website, this detail will be shown in your created room.
+- **slot name** (e.g. `Player`)
+   * This is your player name, which you chose along with your player options.
+- **password** (e.g. `123456`)
+  * If the room does not have a password, it can be left empty.
+
+This configuration persists through launches and even updates.
+
+With your settings filled, start a connection attempt by pressing on the title screen's "CONNECT!" button.
+
+Once connected, the button will become one of either "NEW GAME" or "CONTINUE".
+The game automatically keeps a save file for each seed and slot combination, so you do not need to manually move or delete save files.
+
+All that's left is pressing on the button again to start playing. If you are waiting for a countdown, press "NEW GAME" when the countdown finishes.
+
+## Gameplay Questions
+
+### Do I need to save the game before I stop playing?
+
+It is safe to close the game at any point while playing, your progress will be kept.
+
+### What happens if I lose connection?
+
+If a disconnection occurs, you will see the HUD connection indicator go grey.
+From here, the game will automatically try to reconnect.
+You can tell it succeeded if the indicator regains its color.
+
+If the game is unable to reconnect, save and restart.
+
+Although you can keep playing while disconnected, you won't get any items until you reconnect, not even items found in your own game.
+Once reconnected, however, all of your progress will sync up.
+
+### I got an item, but it did not say who sent it to me
+
+Items sent to you by yourself do not list the sender.
+
+Additionally, if you get an item while already having the max for that item (for example, you have 9 ammo and get sent a Clip Extension), no message will be shown at all.
+
+### I pressed the release/collect button, but nothing happened
+
+It is likely that you do not have release or collect permissions, or that there is nothing to release or collect.
+Another option is that your connection was interrupted.
+
+If you would still like to use release or collect, refer to [this section of the server commands page](https://archipelago.gg/tutorial/Archipelago/commands/en#collect/release).
+
+You may use the in-game console to execute the commands, if your slot has permissions to do so.
+
+### I am trying to configure my controller, but the menu keeps closing itself
+
+Steam Input will make your controller behave as a keyboard and mouse even while not playing any Steam games.
+
+To fix this, simply close Steam while playing Saving Princess.
+
+Another option is to disable Steam Input under `Steam -> Settings -> Controller -> External Gamepad Settings`