pokevial - PokemonSanFran/pokeemerald GitHub Wiki

Pokévial Header

Introduction

This branch allows developers to use the Pokévial item in their decomp projects. This item (or similar items) is found in many classic RPGs. This implementation was inspired by the Pokévial found in Inclement Emerald, Radical Red, or the Temessence Phial from Temtem.

Thank you very much to BuffelSaft and Karathan for their contributions. Please read more about their contributions and support their projects!

Features

Heal Party

The Pokévial heals the player's party.

Skip Party Cutscene

When POKEVIAL_SKIP_CUTSCENE is set to TRUE in include/pokevial.h, the Pokévial will not go to the party scene and simply print a message to indicate that the item worked.

Field Bag
Player using the Pokévial from the field with the cutscene skipped. Player using the Pokévial from the bag with the cutscene skipped.

Doses / Size

The Pokévial can only be used a set number of times, measured in doses. The maximum number of doses a player can have at a time is measured by the size of the Pokevial. Once the doses are empty, the Pokévial cannot be used again until it is refilled.

Developers can control the number of doses or the size of the Pokevial, (up to 15).

Refill

The Pokévial is refilled when the player heals their full party (either at a Pokemon Center or a rest stop).

Dose Indicator

<img alt="Image of a vial that is 50% filled" src"" width=480 height=320><img alt="Image of a vial that is 75% filled" src"" width=480 height=32>

The item icon in the bag shows a visual indicator of the current number of doses, relative to the size of the Pokévial.

Installation

These instructions assume that you can build pokeemerald, have a basic understanding of C, and are familiar with using the in-game scripting language. If you do not, please watch the tutorials series from Team Aqua's Hideout.

git merge (recommended)

From the root directory of your project, run the following commands in your terminal program of choice:

git remote add psf-emerald https://github.com/PokemonSanFran/pokeemerald/ # This adds our team's pokeemerald branch as a remote repo.
git pull psf-emerald pokevial # This pulls in the pokevial feature branch

Manual merge

If your project is:

  • Too far behind pokeemerald
  • Using a different base (pokeemerald-expansion or pokefirered)
  • Some other reason that I can't think of

You can manually implement the features using the diff between this branch and vanilla pokeemerald as a guide. You will need to manually edit or create each of these files in your project to properly recreate the feature.

Warnings

Saveblock1 space

This item's memory consumes 8 bytes of space in gSaveblock1. 4 bytes for doses, and 4 bytes the Pokévial size. 15 is the largest value stored in 4 bytes, which means the Pokévial is limited to 15 doses. In theory, a developer could increase this size by either removing the bitfield delcaration on the members of gSaveBlock1Ptr->pokevial, or by increasing them from u8 to u16 or u32. This would also require manually redefining VIAL_DOSE_MASK, VIAL_SIZE_MASK, and VIAL_MAX_SIZE. Conversely, a developer could decrease the size to a single byte by only storing a single dose - either the player can or cannot use the Pokévial.

Usage

Pokévial Player Flow

Mermaid chart explaining the flow of the Pokevial

Doses

The player can use the Pokévial for as many doses as they currently have. The maximum number of doses is determined by the size of the Pokevial. The number of doses can be refilled.

GetDose

Doses are stored in gSaveBlock1Ptr->pokevial.Dose. GetDose returns the current number of doses.

DoseDown

This is used to decrease the current number of doses. The current number of doses will never equal less than 0. One dose is automatically consumed every time player successfully uses the Pokévial. This can be changed by changing the value of VIAL_STANDARD_DOSE.

This can be used as a smaller punishment for players.

DoseUp

This is used to increase the current number of doses. If the player's current number of doses + X would be greater than the Pokevial's current size, the player will be left with a number of doses equal to the current size.

This can be used to help the player through a difficult dungeon or stretch of Trainers.

Size

The size of the Pokévial limits the maximum number of doses that a player has at any given point in time. The size can be changed by the developer.

GetSize

Size is are stored in gSaveBlock1Ptr->pokevial.Size. GetSize returns the current size of the Pokévial.

SizeDown

This is used to decrease the size of the Pokevial. The size of the Pokévial will never be less than VIAL_MIN_SIZE. If the current number of doses is greater than the size of the Pokevial, the number of doses is reduced to match the size of the Pokevial.

This can be used by developers to modify the difficulty of a specific portion of the game, or punish the player for failing to complete a task.

SizeUp

This is used to increase the size of the Pokevial. The size of the Pokévial will never be greater than VIAL_MAX_SIZE.

This can be used by developers to reward the player for completing a quest or winning a difficult battle.

Refill

Increases the current number of doses to match the current size of the Pokevial.

This automatically occurs when HealPlayerParty, which is the scripting command that is used to heal the player's party (both in and out of a Pokemon Center).

Scripting Macros

pokevialgetdose: Returns the current number of doses and stores it in VAR_0x8006.

specialvar X,PokevialGetDose: Returns the current number of doses and stores it in the location X specified by the developer, such as VAR_0x8005.

pokevial GET, DOSE: Returns the current number of doses, but does not store it anywhere.

pokevialremovedose: Removes VIAL_STANDARD_DOSE dose from the current number of doses.

pokevial VIAL_REMOVE, VIAL_DOSE X: Removes X doses from the current number of doses.

pokevialadddose: Adds VIAL_STANDARD_DOSE dose to the current number of doses.

pokevial VIAL_ADD, VIAL_DOSE X: Adds X doses to the current number of doses.

pokevialgetsize: Returns the size of the Pokévial and stores it in VAR_0x8006.

specialvar X,PokevialGetSize: Returns the size of the Pokévial and stores it in the location X specified by the developer, such as VAR_0x8006.

pokevial GET, SIZE: Returns the current number of doses, but does not store it anywhere.

pokevialdecreasesize: Decreases the size of the Pokévial by 1.

pokevial VIAL_DECREASE,VIAL_SIZE X: Decreases the size of the Pokévial by X.

pokevialincreasesize: Increases the size of the Pokévial by 1.

pokevial VIAL_INCREASE,VIAL_SIZE X: Increases the size of the Pokévial by X.

pokevialreward: Increases the size of the Pokévial by 1, refills the Pokevial, returns the success status, and stores the result in VAR_RESULT.

pokevialrefill: Refills the Pokevial, returns the success status, and stores the result in VAR_RESULT.

specialvar X,PokevialRefill: Refills the Pokevial, returns the success status, and stores it in the location X spe cified by the developer, such as VAR_0x8006.

pokevial REFILL: Refills the Pokevial, returns the success status, but does not store it anywhere.

pokevial: The master macro for interacting with the Pokevial. It takes three arguments, mode, aspect, and amount, but the latter two optional.

pokevial Arguments

mode: What operation are you trying to perform?

mode description aliases
VIAL_GET Get the value of the aspect. VIAL_CHECK
VIAL_UP Add to an aspect. VIAL_INCREASE, VIAL_ADD, VIAL_GROW
VIAL_DOWN Subtract from an aspect. VIAL_DECREASE, VIAL_REMOVE, VIAL_SUBTRACT, VIAL_SHRINK, VIAL_REDUCE
VIAL_REFILL Make the number of doses equal to size. VIAL_REFRESH, VIAL_RESTORE

aspect: What property of the Pokévial do you want to use? Ignored in VIAL_REFRESH mode. When left blank, aspect assumes VIAL_SIZE.

aspect description
VIAL_DOSE The current number of doses available to the player.
VIAL_SIZE The total number of doses available to the player.

amount: What value do you want Pokévial to add or remove? Ignored when in VIAL_REFILL, or VIAL_GET modes. When left blank, amount assumes 1.

Examples

  • pokevial VIAL_CHECK,VIAL_DOSE: Check the number of current doses.
  • pokevial VIAL_UP,VIAL_SIZE,15: Increase the size of the vial by 15.
  • pokevial VIAL_DOWN,VIAL_DOSE,5: Reduce the current number of doses by 5.
  • pokevial VIAL_REFRESH: Set the current number of doses equal to the size of the Pokevial.
  • pokevial VIAL_ADD,VIAL_DOSE,7: Increase the current number of doses by 7.
  • pokevial VIAL_DECREASE,VIAL_SIZE,12: Decrease the size of the vial by 12.

Initialize

When pokeemerald's save data is first initalized, the size of the Pokévial is set to 0. This means the vial cannot hold any doses, making it unusable. When the Pokévial is interacted with (loading the item icon, refilling, using the item) and size is 0, the vial size and the number of doses are set to VIAL_MIN_SIZE.

GetDoseIcon

When the game loads the item icon for the Pokévial, (doses / size) is used to dynamically load a different icon for the Pokévial. This is a percentage, and so 1 dose in a 2 size vial will look the same as 4 doses in a 8 size vial. Developers can make this absolute instead of relative by modiyfying PokevialGetVialPercent to return dose directly. VIAL_NUM_STATES, and pokevialIconIndex will need to be updated to support VIAL_MAX_SIZE number of states.

Known Issues

This isn't an issue, but I would love to figure out how to write a macro that automatically adjusts the values of VIAL_DOSE_MASK, VIAL_SIZE_MASK, and VIAL_MAX_SIZE based on the size of the Pokevial member.

Support

Frequently Asked Questions (FAQ)

n/a

Other Questions

If you have read all of the documentation here and still have questions, please ask a good question in the pokeemerald channel of the pret Discord server. You can tag pkmnsnfrn and we will try to help if we can.

Donations

If you got some use out of this feature, please consider donating. We are currently not taking any donations, so please donate to some of our favorite charities.

Contributors

BuffelSaft

  • Provided the Pokévial sprite for use

Karathan#1337

  • Refactored Task_PokevialLoop,
  • Suggested use of bitfields and converting pokevial into a struct for increased reability and use of use

RavePossum

  • Updated branch to properly build when using modern compiler

CHANGELOG

All changes to this project will be documented in this section. The format is based on Keep a Changelog, and this project tries to adhere to Semantic Versioning.

Unreleased

n/a

[1.1.0] - 2025-04-18

Added

  • Added ability to skip the Pokevial cutscene via the config POKEVIAL_SKIP_CUTSCENE. Suggested by (Master*) · (8e130d13f)

[1.0.1] - 2024-04-06

Added