Force Spawning

Force Spawning is a feature in the Myths and Legends mod that allows players to use specific Key Items to attempt to trigger an immediate spawn of a Pokémon associated with that item. This provides a way to potentially encounter certain rare Pokémon outside of their normal random spawning chances, but success depends on various factors including server configuration, player status, environment, and Cobblemon's spawning rules.

The behavior of Force Spawning is heavily influenced by server settings in the config.toml file. Key options include:

enable_force_spawning: Enables or disables the entire feature.
Cooldown & Voucher System:
- enable_vouchers: Master switch for cooldowns and usage limits.
- force_spawn_item_cooldown: Cooldown duration (seconds) after use.
- global_item_cooldown: Whether cooldown applies to all items or just the used one.
- force_spawning_vouchers: Maximum number of uses before cooldown applies.
- global_item_vouchers: Whether the usage limit is shared across all items.
Spawning Parameters:
- force_spawning_spawn_pool: Which spawn rarity pool (e.g., “ultra-rare”) the system checks for matching Pokémon.
- force_spawn_check_width / force_spawn_check_height: The size of the area around the player searched for a valid spawn location.

Refer to the config.toml documentation for detailed explanations of these settings.

There are two ways to initiate a Force Spawn attempt:

Simply right-click while holding a relevant Key Item in your main hand (do not sneak while clicking).
This method, by default, respects the configured cooldowns and consumes one “voucher” or use charge (if the voucher system is enabled in the config).
Key Items typically have a tooltip describing their purpose (defined by `item.mythsandlegends.<itemName>.description` keys).

Players with appropriate permissions can use the /mal forcespawn command.
The command allows specifying:
- The Key Item identifier path (e.g., `azure_flute`).
- A target player (optional, defaults to self).
- Whether to consume a voucher (`consumeVoucher` flag, defaults to false for command).
- Whether to ignore cooldowns (`ignoreCooldown` flag, defaults to false for command).
This provides administrators flexibility to trigger spawns bypassing normal limitations.

When a force spawn is triggered (either by item use or command), the mod performs the following steps on the server:

Check Feature Enabled: Verifies if `enable_force_spawning` is `true` in the config.
Check Player Data: Ensures the triggering player actually possesses the required Key Item according to the mod's tracked data (obtained via /mal syncitems or automatic checks). Simply having the item in inventory might not be enough if data is out of sync.
Check Cooldowns/Vouchers (if applicable): If triggered by item use, or if the command flags dictate, it checks if the item (or all items, if global) is on cooldown or if the player has exceeded their usage limit (vouchers).
Apply Cooldown/Consume Voucher: If the previous checks pass, the cooldown is applied visually and internally, and a usage count/timestamp is recorded *before* the spawn attempt proceeds.
Search Area: Scans a defined area around the player (based on config width/height) for valid locations where a Pokémon could potentially spawn according to Cobblemon's rules (e.g., correct block type, light level, space).
Find Matching Pokémon: Checks the potential spawns within the configured `force_spawning_spawn_pool` (e.g., “ultra-rare”). It specifically looks for Pokémon whose spawn conditions include a requirement for the exact Key Item that was used to trigger the attempt.
Attempt Spawn: If a valid location is found AND a Pokémon matching the Key Item condition is selected, the mod attempts to spawn that Pokémon.
Feedback: The player receives a chat message indicating the outcome (success, failure, or specific error).

Important: Success is not guaranteed. Factors like being in the wrong biome/location, time of day, lack of suitable spawn spots nearby, or no Pokémon being configured to spawn with that specific Key Item in the chosen pool can all lead to failure, even if cooldowns and vouchers were consumed.

Feedback Messages

You may receive various chat messages indicating the result of your force spawn attempt. Here are the common ones (placeholders like `%s`, `%1$s`, `%2$s` are usually replaced with item or Pokémon names):

commands.mythsandlegends.forcespawn.success_spawned: “Successfully spawned %s!”
- Success! The Pokémon (name replaces %s) was spawned.
commands.mythsandlegends.forcespawn.success: “Successfully triggered spawn for %1$s using %2$s.”
- Generic success message, might appear if the spawned Pokémon's name couldn't be retrieved.
commands.mythsandlegends.forcespawn.success_no_spawn: “Conditions met for %1$s using %2$s, but no spawn occurred (e.g., no valid location or matching Pokémon found).”
- Checks passed, cooldown/voucher used, but final spawn step failed.
commands.mythsandlegends.forcespawn.failure: “Failed to trigger spawn for %1$s using %2$s.”
- Generic failure message when specific error isn’t known.
commands.mythsandlegends.forcespawn.error.disabled: “Force spawning is currently disabled in the server configuration.”
- Feature is turned off in `config.toml`.
commands.mythsandlegends.forcespawn.error.cooldown: “Item '%1$s' is on cooldown (%2$s remaining).”
commands.mythsandlegends.forcespawn.error.cooldown_global: “All key items are on cooldown (%s remaining).”
commands.mythsandlegends.forcespawn.error.no_vouchers: “No remaining vouchers for '%1$s' (Max: %2$s).”
commands.mythsandlegends.forcespawn.error.no_vouchers_global: “You have reached the global limit for key item uses (Max: %s).”
commands.mythsandlegends.forcespawn.error.missing_key_item: “You do not possess the required key item: %s.”
- Try /mal syncitems to refresh key item data.
commands.mythsandlegends.forcespawn.error.invalid_item: “Cannot force spawn: Item '%s' is not a valid key item.”
commands.mythsandlegends.forcespawn.error.no_area: “Could not locate any suitable spawn area nearby.”
commands.mythsandlegends.forcespawn.error.no_context: “Potential spawn points found, but none are suitable under current conditions.”
commands.mythsandlegends.forcespawn.error.no_match: “No Pokémon matching '%s' conditions could be found for spawning.”
commands.mythsandlegends.forcespawn.error.action_failed: “Selected Pokémon spawn failed during final execution.”
commands.mythsandlegends.forcespawn.error.invalid_dimensions: “Configured spawn area dimensions are invalid.”
commands.mythsandlegends.forcespawn.error.invalid_area: “Failed to analyze the specified area for spawning. Check configuration or location.”
commands.mythsandlegends.forcespawn.error.internal: “An internal error occurred during force spawn: %s.”
commands.mythsandlegends.forcespawn.error.generic: “An unexpected error occurred while attempting to spawn %1$s using %2$s.”