🚀 快速开始：3步开发模组

{
  "modId": "my-first-mod",
  "name": "我的第一个模组",
  "version": "1.0.0",
  "author": "你的名字",
  "description": "模组介绍（不超过26字）",
  "entryClass": "com.example.mymod.MyModMain",
  "supportedMcVersions": ["1.20.1", "1.21.4", "26.2"],
  "dependencies": [],
  "website": "",
  "icon": "icon.png"
}

package com.example.mymod;

// ==========================================
// 🔴 核心依赖：smalo-api.jar + smartapi-core.jar
//    打包脚本自动添加，你不用管！
// ==========================================

// 【推荐保留】日志：在控制台打印信息，方便调试
import com.smalo.api.util.Logger;

// 【事件系统】监听游戏里发生的事
import com.smalo.api.event.EventBus;
import com.smalo.api.event.PlayerLoginEvent;  // 玩家登录事件

// 【玩家操作】给玩家发消息、传送、给物品等
import com.smalo.api.player.PlayerHelper;

// 其他想用什么功能，就import对应的包，不用的别引！

public class MyModMain {

    /**
     * 🔑 SMALO启动模组时自动调用这个方法
     * 所有初始化逻辑都写在这里
     */
    public void onInitialize() {
        Logger.info("✅ 我的第一个模组加载成功！");

        // 订阅事件：玩家登录时触发
        EventBus.subscribe(PlayerLoginEvent.class, event -> {
            // 给玩家发彩色欢迎消息
            // §a=绿色 §e=黄色 §6=金色，颜色代码同原版
            PlayerHelper.sendMessage(event.getPlayer(),
                "§a欢迎来到服务器！§e我的模组已加载~");
        });
    }
}

import com.smalo.api.event.EventBus;
import com.smalo.api.event.你要监听的事件类;

// 在 onInitialize() 里订阅事件
EventBus.subscribe(事件类.class, event -> {
    // 事件触发时执行你的代码
    // event 对象里包含事件相关的所有数据
});

import com.smalo.api.event.PlayerChatEvent;

EventBus.subscribe(PlayerChatEvent.class, event -> {
    String msg = event.getMessage();
    if (msg.contains("脏话")) {
        event.setCanceled(true); // 拦截消息，不让发出去
        PlayerHelper.sendMessage(event.getPlayer(), "§c不许说脏话！");
    }
});

import com.smalo.api.registry.ItemRegistry;
import com.smalo.api.item.SmaloItem;
import com.smalo.api.item.ItemSettings;

// 在 onInitialize() 里：
ItemRegistry.register("ruby", () -> new SmaloItem(
    new ItemSettings()
        .maxCount(64)           // 最大堆叠64
        .maxDamage(0)           // 无耐久（工具/武器设耐久）
        .fireproof(false)       // 不是抗火的
))
.setName("§c红宝石")           // 显示名字
.setTexture("ruby.png")       // 贴图（放resources/assets/modid/textures/item/）
.setTooltip("§7闪耀的红色宝石") // 鼠标悬停提示
.setCreativeTab(CreativeTab.MATERIALS); // 创造模式物品栏分类

import com.smalo.api.util.Logger;

// 在代码任何地方调用：
Logger.info("普通信息");           // 白色信息日志
Logger.debug("调试信息");          // 灰色调试日志（生产环境不显示）
Logger.warn("警告信息");           // 黄色警告
Logger.error("错误信息");          // 红色错误
Logger.error("发生异常", exception); // 带异常栈的错误

import com.smalo.api.SmaloMod;

@SmaloMod(
    modId = "my-mod",
    name = "我的模组",
    version = "1.0.0"
)
public class MyModMain {
    public void onInitialize() {
        // ...
    }
}

import com.smalo.api.ModContainer;
import com.smalo.api.SmaloLoader;

ModContainer mod = SmaloLoader.getMod("my-mod");
String modId = mod.getModId();
String version = mod.getVersion();
Path configDir = mod.getConfigDir(); // 模组配置文件夹
Path dataDir = mod.getDataDir();     // 模组数据文件夹

import com.smalo.api.player.PlayerHelper;
import static com.smalo.api.util.ChatColor.*;

// 给玩家发标题
PlayerHelper.sendTitle(player,
    GOLD + BOLD + "欢迎",    // 大标题
    GREEN + "进入服务器",    // 副标题
    10, 70, 10);             // 淡入10tick，停留70tick，淡出10tick

// 传送到主城
PlayerHelper.teleport(player, 0, 64, 0);

// 给玩家64个钻石
PlayerHelper.giveItem(player, Items.DIAMOND, 64);

// 粒子特效：在玩家位置生成本地粒子
PlayerHelper.spawnParticle(player,
    ParticleTypes.HEART,
    player.getX(), player.getY() + 2, player.getZ(),
    10, 0.5, 0.5, 0.5, 0.1);

import com.smalo.api.world.WorldHelper;
import com.smalo.api.world.BlockPos;
import com.smalo.api.world.BlockState;

// 在玩家位置放一个钻石块
BlockPos pos = new BlockPos(player.getBlockX(), player.getBlockY() - 1, player.getBlockZ());
WorldHelper.setBlock(player.world, pos, Blocks.DIAMOND_BLOCK);

// 获取某位置的方块
BlockState state = WorldHelper.getBlock(player.world, pos);
if (state.is(Blocks.DIAMOND_BLOCK)) {
    player.sendMessage("§a你站在钻石块上！");
}

// 用WorldEdit填充区域
WorldEdit.fill(player.world,
    new BlockPos(0, 60, 0),      // 起点
    new BlockPos(10, 70, 10),    // 终点
    Blocks.GOLD_BLOCK);          // 填充金块

import com.smalo.api.item.ItemBuilder;
import com.smalo.api.item.EnchantmentHelper;
import static com.smalo.api.util.ChatColor.*;

// 链式创建一把神剑
ItemStack godSword = new ItemBuilder(Items.DIAMOND_SWORD)
    .setName(RED + BOLD + "神剑·灭世")         // 自定义名字
    .addLore(GRAY + "传说中的武器")             // 第一行介绍
    .addLore(GOLD + "攻击力: +100")             // 第二行介绍
    .addEnchantment(Enchantments.SHARPNESS, 10) // 锋利10
    .addEnchantment(Enchantments.FIRE_ASPECT, 5) // 火焰附加5
    .addEnchantment(Enchantments.UNBREAKING, 10) // 耐久10
    .addEnchantment(Enchantments.MENDING, 1)    // 经验修补
    .setUnbreakable(true)                      // 无法破坏
    .setAttackDamage(100)                      // 攻击力100
    .glow()                                    // 附魔发光效果
    .build();

// 给玩家
PlayerHelper.giveItem(player, godSword);

import com.smalo.api.entity.EntityHelper;
import com.smalo.api.entity.EntityAttribute;
import com.smalo.api.entity.EntityEquipment;
import com.smalo.api.item.ItemStack;
import net.minecraft.world.entity.EntityType;
import net.minecraft.world.item.Items;
import net.minecraft.world.effect.MobEffects;
import net.minecraft.world.effect.MobEffectInstance;

// 在玩家前方3格生成一只BOSS级僵尸
LivingEntity zombie = EntityHelper.spawn(
    player.world,
    EntityType.ZOMBIE,
    player.getX() + 3, player.getY(), player.getZ()
);

// 设置名字和属性
EntityHelper.setCustomName(zombie, "§c§l僵尸王");
EntityHelper.setCustomNameVisible(zombie, true);
EntityAttribute.setMaxHealth(zombie, 200);    // 200血
EntityAttribute.setHealth(zombie, 200);
EntityAttribute.setAttackDamage(zombie, 15);   // 攻击15
EntityAttribute.setMovementSpeed(zombie, 0.35); // 移速加快
EntityHelper.setBaby(zombie, false);

// 给僵尸穿装备
EntityEquipment.setHelmet(zombie, new ItemStack(Items.DIAMOND_HELMET));
EntityEquipment.setChestplate(zombie, new ItemStack(Items.DIAMOND_CHESTPLATE));
EntityEquipment.setLeggings(zombie, new ItemStack(Items.DIAMOND_LEGGINGS));
EntityEquipment.setBoots(zombie, new ItemStack(Items.DIAMOND_BOOTS));
EntityEquipment.setMainHand(zombie, new ItemStack(Items.DIAMOND_SWORD));

// 给僵尸加力量效果
zombie.addEffect(new MobEffectInstance(MobEffects.DAMAGE_BOOST, 999999, 2));

import com.smalo.api.chat.TextComponent;
import static com.smalo.api.util.ChatColor.*;

TextComponent message = new TextComponent(GOLD + "[传送]" + GREEN + "点击传送到主城 ");
TextComponent clickHere = new TextComponent(AQUA + BOLD + "[点我]");
clickHere.setClickEvent(new ClickEvent(ClickEvent.Action.RUN_COMMAND, "/spawn"));
clickHere.setHoverEvent(new HoverEvent(HoverEvent.Action.SHOW_TEXT,
    new TextComponent(GRAY + "点击立即传送到主城")));
message.addExtra(clickHere);
PlayerHelper.sendMessage(player, message);

import com.smalo.api.config.ConfigFile;
import com.smalo.api.SmaloLoader;
import java.nio.file.Path;

// 获取模组配置目录，自动创建config文件
Path configPath = SmaloLoader.getMod("my-mod").getConfigDir().resolve("config.json");
ConfigFile config = new ConfigFile(configPath);

// 设置默认值（如果文件里没有这个键，就用默认值）
config.setDefault("welcome-message", "§a欢迎来到服务器！");
config.setDefault("teleport-cooldown", 30);
config.setDefault("enable-pvp", true);

// 读取配置
String welcomeMsg = config.getString("welcome-message");
int cooldown = config.getInt("teleport-cooldown");
boolean pvpEnabled = config.getBoolean("enable-pvp");

// 修改配置并保存
config.set("teleport-cooldown", 60);
config.save(); // 写入文件

import com.smalo.api.config.PlayerDataManager;

PlayerDataManager pdb = new PlayerDataManager("my-mod", "player_data");

// 玩家登录时，初始化数据（默认0金币）
EventBus.subscribe(PlayerLoginEvent.class, event -> {
    var player = event.getPlayer();
    pdb.initData(player, data -> {
        data.setDefault("coins", 0);
        data.setDefault("kills", 0);
        data.setDefault("deaths", 0);
    });
});

// 给玩家加金币
int coins = pdb.get(player).getInt("coins");
pdb.get(player).set("coins", coins + 100);
pdb.get(player).save();

// 查询玩家击杀数
int kills = pdb.get(player).getInt("kills");

import com.smalo.api.task.TaskScheduler;

// 延时5秒（100tick）后执行
TaskScheduler.scheduleDelayed(() -> {
    PlayerHelper.sendMessage(player, "§e5秒到了！");
}, 100);

// 每隔1秒（20tick）重复执行
TaskScheduler.scheduleRepeating(() -> {
    PlayerHelper.sendMessage(player, "§e每秒弹一次消息");
}, 0, 20);

// 异步执行IO操作（不卡游戏主线程）
AsyncTask.runAsync(() -> {
    // 这里执行耗时操作：HTTP请求、文件读写、数据库查询
    String result = httpClient.get("https://api.example.com/data");

    // 异步操作完成后，回到主线程操作游戏
    TaskScheduler.scheduleDelayed(() -> {
        PlayerHelper.sendMessage(player, "§a数据加载完成：" + result);
    }, 0);
});

import com.smalo.api.command.*;
import static com.smalo.api.command.Commands.*;

CommandRegistry.register("heal", "治疗自己", (ctx) -> {
    Player player = ctx.getPlayer();
    player.setHealth(20);
    player.getFoodData().setFoodLevel(20);
    PlayerHelper.sendMessage(player, "§a你已经被治疗！");
    return 1;
})
.requires(src -> src.hasPermission("mymod.heal")) // 需要权限
.then(argument("玩家", PlayerArgument.player())  // 可以带参数：/heal 玩家名
    .executes(ctx -> {
        Player target = PlayerArgument.getPlayer(ctx, "玩家");
        target.setHealth(20);
        PlayerHelper.sendMessage(target, "§a你被管理员治疗了！");
        PlayerHelper.sendMessage(ctx.getPlayer(), "§a已治疗 " + target.getName().getString());
        return 1;
    })
);

import com.smalo.api.entity.spawn.SpawnEggRegistry;
import com.smalo.api.entity.spawn.SpawnEggItem;
import com.smalo.api.entity.spawn.EntityTypeMapping;
import java.util.List;

// 注册自定义刷怪蛋
SpawnEggRegistry.register("mymod:custom_mob", 
    "自定义生物蛋", 
    EntityTypeMapping.map("mymod:custom_mob"));

// 获取所有内置刷怪蛋
List<SpawnEggItem> eggs = SpawnEggRegistry.getBuiltinEggs();

# 编译（确保smalo-api.jar和smartapi-core.jar在classpath）
javac -encoding UTF-8 -cp "path/to/smalo-api.jar;path/to/smartapi-core.jar" -d build/classes src/main/java/com/example/mymod/*.java

# 打包成JAR（确保smalo.mod.json在根目录）
cd build/classes
jar cf ../../my-mod.jar .
cd ../../my-mod
jar uf ../my-mod.jar smalo.mod.json

# 把成品JAR复制到mods文件夹（版本隔离目录下的mods文件夹）
copy my-mod.jar "%USERPROFILE%\Desktop\SMALO\versions\{版本名}-SMALO\mods\"