Stardew Valley weapon IDs are stable numeric codes used to reference specific weapons in mods, config files, and data packs. This reference explains how IDs are assigned, where to find reliable lists, and how to use them safely when editing or wiring tools, weapons, and behaviors in mods and scripts. It focuses on evergreen usage patterns rather than temporary quirks that change across minor updates.
What Are Weapon IDs and Where Are They Defined
In Stardew Valley’s code and many mods, each weapon has a unique integer ID that scripts and data files use instead of the item name. These IDs are defined in the game’s internal content files and are exposed by modding APIs and data packs. Understanding where these numbers come from helps you avoid broken references when item orders change or translations differ.
Core ID Sources and Version Scope
- ObjectData in ContentPatcher and similar tokens: maps weapon names to IDs.
- Mod APIs such as SpaceCore or Object Manager patches: expose consistent numeric IDs.
- Data files from community tools: often include legacy and expanded IDs.
How IDs Are Assigned and Organized
Weapons are typically grouped by type and tier, with ranges reserved for swords, daggers, spears, and staves. The base ID usually reflects the group and power level, making it possible to infer relationships between IDs. This structure remains stable across most versions, which makes ID-based configs durable when names or order shift slightly.
Key Assignment Patterns
- Swords, daggers, and spears each occupy separate numeric blocks.
- Higher tiers within a weapon type often follow incremental IDs.
- Quest and achievement items may use isolated or special ranges.
Practical Uses in Mods and Configuration
When wiring tools, setting weapon requirements, or translating loot, using numeric IDs reduces ambiguity compared to display names. Many configs and triggers accept weapon IDs to specify effects, unlocks, or tool associations. If you are editing a ContentPatcher rule or a mod’s weapon check, always reference the canonical list rather than guessing numbers.
Common Config Patterns
- Tool upgrade checks: map weapon ID to required level.
- Loot tables: use IDs to filter or replace drops.
- Quest conditions: compare equipped weapon ID to expected value.
Version Differences and Stability Notes
While the numeric IDs are generally stable for vanilla weapons across minor updates, expansions and major versions can introduce new weapons that shift ranges. Mod authors and config writers should prefer official or community-maintained sources over hardcoded assumptions. Always pin the ID list to the game version you are targeting.
Version-Aware Practices
- Test configs on the exact game build you ship with.
- Use ContentPatcher’s asset keys or mod APIs instead of raw numbers when possible.
- Document which ID list version you used and when.
Reliable Sources and Verification
Trust lists that are versioned, include source commit or SMAPI build references, and are maintained by active community tools. Avoid outdated spreadsheets that do not note their origin or date. Cross-check IDs against in-game debug commands or official API reads when precision is critical.
| Attribute | Verified Detail | Source Type |
|---|---|---|
| ID Format | Integer assigned in code and ContentPatcher tokens | API docs, ContentPatcher schema |
| Typical Range | Dozens to low hundreds for vanilla; higher with mods | Community lists, decompilations |
| Version Drift | New entries may extend ranges; old entries rarely change | Patch notes, asset comparisons |
| Use Case | Configs, triggers, lua or mod APIs that accept numeric IDs | Mod documentation, example configs |
| Verification | Cross-check with in-game debug or authoritative API read | SMAPI, debug console, versioned repo |
Best Practices and Safety Tips
When working with weapon IDs, prefer high-integrity sources, version tags, and automated checks. Wrap raw numbers in comments that state the source and date, and avoid editing compiled game files directly unless you understand the risks. For configs, use ContentPatcher asset keys or mod hooks when available; treat raw IDs as a last resort for compatibility or performance needs.
- Pin the ID list to the exact game version.
- Log or comment the origin of each ID used in your mod or config.
- Run integration tests on the target build before publishing.
- Prefer API-supplied IDs over hardcoded numbers when possible.
When to Consult the Canonical List
Before releasing a mod or config that relies on weapon IDs, check the canonical list for the target SMAPI and game version. If you are supporting multiple versions, prepare fallback entries or conditional logic. This approach minimizes incompatibility and reduces support burden as players update their saves or move between versions.
Wrapping Up
Stardew Valley weapon IDs are a durable and practical way to reference weapons in configs and mods when used with up-to-date, version-aware sources. By understanding how IDs are assigned, verifying them against authoritative lists, and documenting your assumptions, you can build configs and mods that remain reliable across patches and translations.