# 🔧 Valorant Powers Mod - Developer Guide ## 📋 Table of Contents 1. [Architecture Overview](#architecture-overview) 2. [Adding New Agents](#adding-new-agents) 3. [Creating Custom Abilities](#creating-custom-abilities) 4. [Custom Entities & Projectiles](#custom-entities--projectiles) 5. [Data Persistence](#data-persistence) 6. [Networking](#networking) 7. [Testing](#testing) --- ## 🏗️ Architecture Overview ### Core Components ``` ValorantPowersMod/ ├── ability/ # Ability system framework │ ├── Ability.java (Interface for all abilities) │ ├── AbilitySlot.java (Enum: ABILITY_1, ABILITY_2, ULTIMATE) │ └── Abilities.java (Registry initializer) ├── agent/ # Agent system │ ├── Agent.java (Enum: all agents) │ ├── AgentRegistry.java (Maps agents to abilities) │ └── abilities/ (Implementation packages) │ ├── jett/JettAbilities.java │ ├── sage/SageAbilities.java │ └── ... (one package per agent) ├── attachment/ # Player data storage │ └── PlayerAbilityData.java ├── entity/ # Custom entities │ ├── ModEntities.java │ └── projectile/ ├── network/ # Client-server communication │ ├── ModPackets.java │ └── packet/ ├── keybind/ # Input handling │ └── ModKeybinds.java ├── event/ # Server tick logic │ └── ServerTickHandler.java └── gui/ # UI screens └── AgentSelectionScreen.java ``` ### Data Flow ``` [Player presses key] ↓ [Client: ModKeybinds detects] ↓ [Client sends UseAbilityC2SPacket] ↓ [Server: ModPackets receives] ↓ [Check cooldown in PlayerAbilityData] ↓ [Execute ability.use(player)] ↓ [Set cooldown in PlayerAbilityData] ↓ [ServerTickHandler decrements cooldowns] ``` --- ## 🎭 Adding New Agents ### Step 1: Add to Agent Enum **File:** `src/main/java/com/valorantpowers/agent/Agent.java` ```java public enum Agent { // ... existing agents ... NEWAGENT("newagent", "New Agent", 0xFF00FF); // Constructor params: id, displayName, color } ``` **Parameters:** - `id`: Lowercase, no spaces (used in data) - `displayName`: Readable name shown to players - `color`: Hex color code for UI theming ### Step 2: Create Abilities Package Create: `src/main/java/com/valorantpowers/agent/abilities/newagent/NewAgentAbilities.java` ```java package com.valorantpowers.agent.abilities.newagent; import com.valorantpowers.ability.Ability; import net.minecraft.server.network.ServerPlayerEntity; public class NewAgentAbilities { public static final Ability FIRST_ABILITY = new Ability() { @Override public String getName() { return "First Ability"; } @Override public int getCooldownTicks() { return 400; // 20 ticks = 1 second } @Override public boolean canUse(ServerPlayerEntity player) { // Add conditions here (e.g., health check, world check) return true; } @Override public void use(ServerPlayerEntity player) { // Implement ability logic sendMessage(player, "§aAbility activated!"); } }; public static final Ability SECOND_ABILITY = new Ability() { // Implement second ability }; public static final Ability ULTIMATE = new Ability() { // Implement ultimate }; } ``` ### Step 3: Register in AgentRegistry **File:** `src/main/java/com/valorantpowers/agent/AgentRegistry.java` ```java public static void initialize() { // ... existing registrations ... registerAgent(Agent.NEWAGENT, NewAgentAbilities.FIRST_ABILITY, NewAgentAbilities.SECOND_ABILITY, NewAgentAbilities.ULTIMATE ); } ``` ### Step 4: Add Localization **File:** `src/main/resources/assets/valorantpowers/lang/en_us.json` ```json { "agent.valorantpowers.newagent": "New Agent", "ability.valorantpowers.newagent.first": "First Ability", "ability.valorantpowers.newagent.second": "Second Ability", "ability.valorantpowers.newagent.ultimate": "Ultimate Name" } ``` **Done!** The agent is now playable. --- ## ⚡ Creating Custom Abilities ### Ability Template ```java public static final Ability ABILITY_NAME = new Ability() { @Override public String getName() { return "Display Name"; } @Override public int getCooldownTicks() { // 20 ticks = 1 second // 200 = 10 seconds // 1200 = 60 seconds return 600; // 30 seconds } @Override public boolean canUse(ServerPlayerEntity player) { // Return false to prevent usage if (player.isCreative()) { return true; // Creative always can use } // Example: require ground if (!player.isOnGround()) { sendMessage(player, "§cMust be on ground!"); return false; } return true; } @Override public void use(ServerPlayerEntity player) { // Your ability implementation // Common operations: // - player.addStatusEffect(new StatusEffectInstance(...)) // - player.setVelocity(...) // - player.teleport(x, y, z) // - player.getWorld().spawnEntity(...) // - player.damage(...) // - player.heal(amount) sendMessage(player, "§aAbility used!"); } }; ``` ### Common Ability Patterns #### 1. **Dash/Movement** ```java @Override public void use(ServerPlayerEntity player) { Vec3d direction = player.getRotationVector(); Vec3d velocity = direction.multiply(2.5); // Speed multiplier player.setVelocity(velocity.x, velocity.y * 0.5, velocity.z); player.velocityModified = true; } ``` #### 2. **Area of Effect** ```java @Override public void use(ServerPlayerEntity player) { Vec3d center = player.getPos(); Box area = new Box(center, center).expand(5.0); // 5 block radius List entities = player.getWorld().getEntitiesByClass( LivingEntity.class, area, entity -> entity != player ); for (LivingEntity entity : entities) { entity.addStatusEffect(new StatusEffectInstance( StatusEffects.SLOWNESS, 100, // Duration in ticks 2 // Amplifier )); } } ``` #### 3. **Projectile** ```java @Override public void use(ServerPlayerEntity player) { CustomProjectileEntity projectile = new CustomProjectileEntity( player.getWorld(), player ); projectile.setPosition(player.getEyePos()); projectile.setVelocity( player, player.getPitch(), player.getYaw(), 0.0F, // Roll 2.5F, // Speed 1.0F // Divergence ); player.getWorld().spawnEntity(projectile); } ``` #### 4. **Raycast** ```java @Override public void use(ServerPlayerEntity player) { Vec3d start = player.getEyePos(); Vec3d end = start.add(player.getRotationVector().multiply(50.0)); HitResult hit = player.getWorld().raycast(new RaycastContext( start, end, RaycastContext.ShapeType.OUTLINE, RaycastContext.FluidHandling.NONE, player )); if (hit.getType() != HitResult.Type.MISS) { // Do something at hit.getPos() } } ``` #### 5. **Particles** ```java @Override public void use(ServerPlayerEntity player) { player.getServerWorld().spawnParticles( ParticleTypes.FLAME, // Particle type player.getX(), // X position player.getY() + 1, // Y position player.getZ(), // Z position 20, // Count 0.5, 0.5, 0.5, // Spread (x, y, z) 0.1 // Speed ); } ``` #### 6. **Delayed Effect** ```java @Override public void use(ServerPlayerEntity player) { player.getWorld().getServer().execute(() -> { try { Thread.sleep(2000); // 2 second delay } catch (InterruptedException e) { Thread.currentThread().interrupt(); } // Execute delayed effect player.heal(10.0F); }); } ``` #### 7. **Toggle Ability** ```java @Override public void use(ServerPlayerEntity player) { PlayerAbilityData data = PlayerAbilityData.get(player); Boolean active = data.getData("ability_active", Boolean.class); if (active == null || !active) { // Turn ON player.addStatusEffect(new StatusEffectInstance( StatusEffects.SPEED, Integer.MAX_VALUE, // Permanent 2 )); data.putData("ability_active", true); sendMessage(player, "§aAbility ON"); } else { // Turn OFF player.removeStatusEffect(StatusEffects.SPEED); data.putData("ability_active", false); sendMessage(player, "§7Ability OFF"); } } ``` --- ## 🎯 Custom Entities & Projectiles ### Creating a Projectile Entity **Step 1: Create Entity Class** `src/main/java/com/valorantpowers/entity/projectile/CustomProjectile.java` ```java package com.valorantpowers.entity.projectile; import com.valorantpowers.entity.ModEntities; import net.minecraft.entity.Entity; import net.minecraft.entity.EntityType; import net.minecraft.entity.LivingEntity; import net.minecraft.entity.projectile.ProjectileEntity; import net.minecraft.entity.projectile.ProjectileUtil; import net.minecraft.nbt.NbtCompound; import net.minecraft.particle.ParticleTypes; import net.minecraft.util.hit.EntityHitResult; import net.minecraft.util.hit.HitResult; import net.minecraft.world.World; public class CustomProjectile extends ProjectileEntity { private int life = 0; public CustomProjectile(EntityType type, World world) { super(type, world); } public CustomProjectile(World world, LivingEntity owner) { super(ModEntities.CUSTOM_PROJECTILE, world); this.setOwner(owner); } @Override public void tick() { super.tick(); // Lifetime check if (!this.getWorld().isClient) { life++; if (life > 100) { // 5 seconds this.discard(); return; } } // Collision detection HitResult hitResult = ProjectileUtil.getCollision(this, this::canHit); if (hitResult.getType() != HitResult.Type.MISS) { this.onCollision(hitResult); } // Movement this.updatePosition( this.getX() + this.getVelocity().x, this.getY() + this.getVelocity().y, this.getZ() + this.getVelocity().z ); ProjectileUtil.setRotationFromVelocity(this, 0.5F); // Client-side particles if (this.getWorld().isClient) { this.getWorld().addParticle( ParticleTypes.FLAME, this.getX(), this.getY(), this.getZ(), 0, 0, 0 ); } } @Override protected void onEntityHit(EntityHitResult entityHitResult) { super.onEntityHit(entityHitResult); Entity entity = entityHitResult.getEntity(); Entity owner = this.getOwner(); if (entity != owner && entity instanceof LivingEntity) { entity.damage( this.getWorld().getDamageSources().magic(), 8.0F // Damage amount ); } this.discard(); } @Override protected void initDataTracker(net.minecraft.entity.data.DataTracker.Builder builder) { // Add tracked data if needed } @Override protected void readCustomDataFromNbt(NbtCompound nbt) { this.life = nbt.getInt("Life"); } @Override protected void writeCustomDataToNbt(NbtCompound nbt) { nbt.putInt("Life", this.life); } } ``` **Step 2: Register Entity Type** `src/main/java/com/valorantpowers/entity/ModEntities.java` ```java public static final EntityType CUSTOM_PROJECTILE = Registry.register( Registries.ENTITY_TYPE, Identifier.of(ValorantPowersMod.MOD_ID, "custom_projectile"), FabricEntityTypeBuilder.create(SpawnGroup.MISC, CustomProjectile::new) .dimensions(EntityDimensions.fixed(0.5F, 0.5F)) .trackRangeBlocks(64) .trackedUpdateRate(10) .build() ); ``` **Step 3: Use in Ability** ```java @Override public void use(ServerPlayerEntity player) { CustomProjectile projectile = new CustomProjectile( player.getWorld(), player ); projectile.setPosition(player.getEyePos()); projectile.setVelocity(player, player.getPitch(), player.getYaw(), 0.0F, 2.5F, 1.0F); player.getWorld().spawnEntity(projectile); } ``` --- ## 💾 Data Persistence ### Using PlayerAbilityData The `PlayerAbilityData` attachment stores data per-player that persists through death and world saves. #### Storing Data ```java PlayerAbilityData data = PlayerAbilityData.get(player); // Store simple values data.putData("key_name", value); // Examples data.putData("ability_uses", 5); data.putData("last_use_time", player.getWorld().getTime()); data.putData("is_active", true); data.putData("spawn_pos", player.getPos()); ``` #### Retrieving Data ```java PlayerAbilityData data = PlayerAbilityData.get(player); // With type safety Integer uses = data.getData("ability_uses", Integer.class); Boolean active = data.getData("is_active", Boolean.class); Vec3d pos = data.getData("spawn_pos", Vec3d.class); // Check for null if (uses != null) { // Use value } // With default fallback int usesCount = uses != null ? uses : 0; ``` #### Removing Data ```java data.removeData("key_name"); ``` ### Persisted vs Temporary Data **Persisted (survives logout):** - Agent selection - Cooldown state (via codec) **Temporary (cleared on logout):** - Custom ability data (putData/getData) - Active effect states - Temporary positions **To make data persist:** Update the codec in `PlayerAbilityData.java` --- ## 🌐 Networking ### Client to Server Packets All ability triggers use `UseAbilityC2SPacket`: ```java ClientPlayNetworking.send(new UseAbilityC2SPacket(AbilitySlot.ABILITY_1)); ``` ### Creating Custom Packets **Step 1: Create Packet Record** ```java package com.valorantpowers.network.packet; import net.minecraft.network.RegistryByteBuf; import net.minecraft.network.codec.PacketCodec; import net.minecraft.network.codec.PacketCodecs; import net.minecraft.network.packet.CustomPayload; import net.minecraft.util.Identifier; public record CustomDataPacket(int value, String text) implements CustomPayload { public static final Id ID = new Id<>(Identifier.of("valorantpowers", "custom_data")); public static final PacketCodec CODEC = PacketCodec.tuple( PacketCodecs.VAR_INT, CustomDataPacket::value, PacketCodecs.STRING, CustomDataPacket::text, CustomDataPacket::new ); @Override public Id getId() { return ID; } } ``` **Step 2: Register Packet** ```java // In ModPackets.java // Server-side PayloadTypeRegistry.playC2S().register(CustomDataPacket.ID, CustomDataPacket.CODEC); ServerPlayNetworking.registerGlobalReceiver(CustomDataPacket.ID, (payload, context) -> { context.player().server.execute(() -> { // Handle packet on server int value = payload.value(); String text = payload.text(); }); }); ``` **Step 3: Send from Client** ```java ClientPlayNetworking.send(new CustomDataPacket(42, "Hello")); ``` --- ## 🧪 Testing ### In-Game Testing Commands ```java // Give yourself the agent selector /give @p valorantpowers:agent_selector // Test in creative mode (bypasses some checks) /gamemode creative ``` ### Debug Messages ```java // Action bar (temporary, non-intrusive) player.sendMessage(Text.literal("Debug: " + value), true); // Chat (persists in log) player.sendMessage(Text.literal("Debug: " + value), false); // Server console ValorantPowersMod.LOGGER.info("Debug: {}", value); ``` ### Testing Checklist - [ ] Ability cooldowns working correctly - [ ] Particles visible to all players - [ ] Projectiles collide properly - [ ] Status effects apply correctly - [ ] Agent switching works - [ ] GUI opens and closes - [ ] Keybinds respond - [ ] Multiplayer synchronization - [ ] No crashes on logout/login - [ ] Data persists across sessions --- ## 📊 Performance Tips ### Particle Optimization ```java // BAD: Spawns 1000 particles per tick for (int i = 0; i < 1000; i++) { world.spawnParticles(...); } // GOOD: Limit particle count if (world.getTime() % 4 == 0) { // Every 4 ticks world.spawnParticles(..., 5, ...); // 5 particles max } ``` ### Tick-based Logic ```java // BAD: Runs expensive logic every tick @Override public void use(ServerPlayerEntity player) { while (condition) { // Heavy computation } } // GOOD: Schedule over multiple ticks @Override public void use(ServerPlayerEntity player) { data.putData("ability_ticks", 100); // Handle in ServerTickHandler } ``` ### Entity Queries ```java // BAD: Query entire world List allEntities = world.getEntitiesByClass(Entity.class, ...); // GOOD: Limit search area Box area = new Box(pos, pos).expand(10.0); // Only 10 blocks List nearbyEntities = world.getOtherEntities(player, area); ``` --- ## 🎨 Code Style - **No comments** (code should be self-explanatory) - **No placeholders** (implement all methods) - **Descriptive names** (`applyDamageInRadius` not `doStuff`) - **Extract complex logic** (create helper methods) - **Use constants** for magic numbers ```java // BAD entity.damage(source, 8.0F); Thread.sleep(2000); // GOOD private static final float ABILITY_DAMAGE = 8.0F; private static final int DELAY_TICKS = 40; // 2 seconds entity.damage(source, ABILITY_DAMAGE); Thread.sleep(DELAY_TICKS * 50L); ``` --- ## 🚀 Deployment ### Building ```bash ./gradlew build ``` Output: `build/libs/valorant-powers-mod-1.0.0.jar` ### Version Bumping Update in `gradle.properties`: ```properties mod_version=1.1.0 ``` ### Changelog Document changes in `CHANGELOG.md`: ```markdown ## [1.1.0] - 2024-XX-XX ### Added - New agent: Chamber - Ultimate ability rebalancing ### Fixed - Jett dash velocity bug - Cooldown desync in multiplayer ``` --- ## 📚 Resources ### Useful Fabric APIs - **Entity Management:** `World.spawnEntity(Entity)` - **Player Data:** `ServerPlayerEntity` methods - **Effects:** `StatusEffectInstance` - **Particles:** `ServerWorld.spawnParticles()` - **Raycasting:** `World.raycast(RaycastContext)` - **Networking:** `ServerPlayNetworking` ### Minecraft Documentation - [Fabric Wiki](https://fabricmc.net/wiki/) - [Yarn Mappings](https://fabricmc.net/wiki/tutorial:mappings) - [Minecraft Wiki](https://minecraft.wiki/) ### This Mod's Documentation - `IMPLEMENTATION_GUIDE.md` - Architecture overview - `SYSTEM_ARCHITECTURE.md` - Technical deep dive - `QUICKSTART.md` - Player guide --- ## 💡 Feature Ideas ### Easy Extensions - Add visual effects to abilities - Create ability sound effects - Add agent voice lines - Create agent-specific items ### Medium Complexity - Ultimate point system (charge ult from kills) - Ability upgrade system - Agent stats/analytics - Custom particle effects ### Advanced Features - Agent-specific passive abilities - Advanced movement mechanics (wall-running, sliding) - Ability combinations (ability A + B = special effect) - Tournament mode with spectator features --- ## 🤝 Contributing 1. Fork the repository 2. Create feature branch (`git checkout -b feature/NewAgent`) 3. Implement and test thoroughly 4. Commit changes (`git commit -am 'Add new agent'`) 5. Push to branch (`git push origin feature/NewAgent`) 6. Create Pull Request ### Contribution Guidelines - Follow existing code structure - Test in singleplayer and multiplayer - Update documentation - No breaking changes without discussion - Maintain Fabric 1.21.4 compatibility --- ## 📬 Support - **Issues:** Report bugs with reproduction steps - **Questions:** Check existing documentation first - **Features:** Open discussion before implementing --- ## 📄 License This mod is provided as-is for educational purposes. Valorant is a trademark of Riot Games. --- **Happy Modding! 🎮**