Ben10Mod

Ben10Mod is a tModLoader mod that adds Ben 10 style transformation gameplay to Terraria.

At a high level:

• follow a strange signal near spawn and recover a damaged Omnitrix core
• show its Codon Sample to the Guide, then repair the Prototype Omnitrix
• equip an Omnitrix in the custom Omnitrix slot
• unlock transformations through bosses, events, and progression
• transform into aliens with their own passives, abilities, and badge attacks
• use a Plumber's Badge as the shared weapon shell for alien attacks

The codebase is structured so built-in content and addon content both plug into the same shared runtime.

Documentation

Use the doc set that matches what you are trying to do:

• Player Guide
• Architecture Guide
• Development Guide
• Addon API Guide
• Licensing Guide
• Asset Provenance Register
• Asset Manifest
• Shader Build Guide
• License History
• Release Checklist
• Changelog
• New-Player Entry Proposal

Current Gameplay Model

These are the important current rules:

• Transformation owns alien-specific behavior: passives, visuals, attacks, abilities, and metadata.
• Omnitrix owns transformation timing, energy rules, swap costs, evolution, and hand visuals.
• PlumbersBadge is a generic weapon shell that asks the current transformation how to behave.
• F, G, H, and U are action keys.
• depending on the transformation and slot, an action key can:
  • activate an immediate or timed ability
  • channel an ability while held
  • or load a badge attack
• badge attacks require the Plumber's Badge to actually fire
• immediate and held abilities do not
• right click while holding a badge swaps between the base primary and secondary badge attacks
• the current loaded attack and its energy cost are shown under the Omnitrix energy bar

Repository Map

Important files and folders:

• Ben10Mod.cs Root mod entry point. Loads shaders and handles packets.
• OmnitrixPlayer.cs Central player-side state for transformations, energy, ability flags, attack selection, progression, and UI-facing state.
• Content/Transformations/ Base transformation API plus built-in transformations.
• Content/Items/Accessories/Omnitrix.cs Base Omnitrix API.
• Content/Items/Weapons/PlumbersBadge.cs Base badge API and shared attack fire path.
• Content/TransformationHandler.cs Shared helper methods for transforming, detransforming, and unlocks.
• Content/Interface/ Roster UI, energy bar, and current-attack HUD.
• Keybinds/KeybindSystem.cs All registered keybinds.
• bossTrackerNPC.cs Boss-based unlock progression.

Quick Start For Contributors

If you want to understand the runtime flow, start here:

1. OmnitrixPlayer.cs
2. Transformation.cs
3. Omnitrix.cs
4. PlumbersBadge.cs
5. TransformationHandler.cs

If you want to build an addon, start here:

1. Addon API Guide
2. a built-in transformation such as HeatBlastTransformation.cs
3. a built-in Omnitrix such as PrototypeOmnitrix.cs

Separate, independently written addons may be released without prior permission when they are free, noncommercial, and do not include or redistribute Ben10Mod code or assets. The only copying exception is for code blocks expressly presented as addon examples in the Addon API Guide. Read the Licensing Guide before distributing an addon.

Build Note

dotnet build Ben10Mod.csproj does two things:

1. compiles the C# project
2. runs tModLoader's packaging/build step

If the C# compile succeeds but the final packaging step fails with an FNA3D error, that is usually a local tModLoader environment problem rather than a gameplay-code error.

Automated Tests

The repository includes a dependency-free test executable for pure runtime policy and documentation consistency:

dotnet run --project tests/Ben10Mod.Tests/Ben10Mod.Tests.csproj

These tests run without launching Terraria. They currently cover Omnitrix energy behavior, unlock-catalogue integrity, and progression lines that must stay synchronized with the player guide.

Repository and release-artifact controls are checked with:

node tools/generate_asset_manifest.mjs --check
node tools/release_audit.mjs
node tools/release_audit.mjs --tmod /path/to/Ben10Mod.tmod

Contributing

Development uses short-lived branches and reviewed pull requests. Before requesting repository access or submitting a change, read CONTRIBUTING.md and the Development Guide.

Do not commit directly to the default branch. Automated tests, resolved review feedback, and approval from the repository owner are expected before a change is merged.

License

Ben10Mod is source-available software, not open-source software. Separate, free, noncommercial addons that depend on Ben10Mod are expressly permitted without prior permission. Redistributing Ben10Mod itself, copying its code or assets into another project, and commercial use are not permitted without written permission. Code blocks expressly presented as addon examples in the Addon API Guide are the limited copying exception described by the license.

Ben10Mod 0.93 was distributed with the MIT License. Rights already granted with that release remain in effect and are not revoked by the current license; see the License History before reusing an older copy.

See LICENSE.txt for the controlling terms, docs/LICENSING.md for the plain-language addon guide, and THIRD_PARTY_NOTICES.md for third-party and provenance information.

Current State

Ben10Mod is still in active development. The shared transformation, Omnitrix, badge, and addon-extension systems are now much more generalized than the early versions of the project, but content balance and presentation are still evolving.

Credits

• Author: DestroyerMob
• Spriter: Eye of Rage
• Discord: https://discord.gg/XD7qN7DbdD