DEPLOY BÓNG MỚI

1. Tổng quan hệ thống

Mỗi đấu sĩ trong game là một package độc lập gồm 1 ảnh sprite + 4 file code JavaScript. Bạn upload cả folder qua trang Admin, hệ thống tự đọc và ghép thành 1 bóng chiến đấu được.

4 file code chia đúng 4 vai trò, mỗi vai trò chạy độc lập với nhau mỗi khung hình (frame):

2. Cấu trúc folder bóng

Tạo 1 folder bất kỳ, đặt tên gì cũng được, bên trong chứa:

Tên file linh hoạt — hệ thống chỉ cần tìm thấy từ khóa trong tên (không phân biệt hoa/thường). weapon_katana.js, WeaponCode.js, my-weapon-v2.js đều nhận diện đúng là "weapon". Nếu thiếu 1 trong 4 vai trò, hoặc thiếu ảnh, Admin sẽ báo lỗi rõ ràng và không lưu.

3. config.json

Hoàn toàn tùy chọn — nếu không có, hệ thống dùng giá trị mặc định. Tất cả field cũng tùy chọn riêng lẻ.

{
  "cols": 4,
  "rows": 1,
  "maxHP": 200,
  "maxSpeed": 4,
  "baseDamage": 8,
  "radius": 28,
  "color": "#4caf50",
  "skillName": "Tên kỹ năng hiển thị",
  "skillDesc": "Mô tả ngắn kỹ năng làm gì"
}

4. weapon.js — Vũ khí chạy mỗi frame

Nhận 3 tham số: (self, ctx, api). Nhiệm vụ: vẽ vũ khí bằng api.drawLine/drawCircle/drawTriangleTip, rồi return vị trí đầu vũ khí để engine tự tính va chạm.

Vũ khí cận chiến (vd kiếm quay quanh thân)

self.weaponAngle = (self.weaponAngle || 0) + 0.12 * self.weaponBoost;
const len = 46, width = 10;
const tipX = self.x + Math.cos(self.weaponAngle) * len;
const tipY = self.y + Math.sin(self.weaponAngle) * len;

api.drawLine(self.x, self.y, tipX, tipY, "#c9d6e3", width);
api.drawCircle(tipX, tipY, width * 0.55, "#e8eef5");

// Bắt buộc: trả về vị trí đầu vũ khí + bán kính va chạm để gây damage
return { tipX, tipY, hitRadius: width / 2 + 14 };

Bóng không có cận chiến (chỉ đánh qua skill)

// Không vẽ gì hoặc chỉ vẽ trang trí, rồi trả về null
return null;

Giá trị trả về (object hoặc null):

5. ai.js — Lối chơi / AI chạy mỗi frame

Nhận (self, enemy, api). Nhiệm vụ duy nhất: chỉnh self.vx / self.vy để điều khiển hướng di chuyển. Vật lý va chạm (nảy tường, va bóng) engine tự lo — AI không thể và không cần can thiệp vào phần đó.

AI đuổi theo (mẫu mặc định, dùng cho bóng cận chiến)

const dx = enemy.x - self.x, dy = enemy.y - self.y;
const dist = Math.sqrt(dx*dx + dy*dy) || 1;
if (api.now % 15 === 0) {
  self.vx += (dx / dist) * 0.9 + (Math.random() - 0.5) * 0.6;
  self.vy += (dy / dist) * 0.9 + (Math.random() - 0.5) * 0.6;
}

AI giữ khoảng cách / né tránh (dùng cho bóng tầm xa)

const dx = enemy.x - self.x, dy = enemy.y - self.y;
const dist = Math.sqrt(dx*dx + dy*dy) || 1;
const desiredDist = 180;
if (api.now % 20 === 0) {
  const away = dist < desiredDist ? -1 : 0.3;
  self.vx += (dx / dist) * away * 1.2 + (Math.random() - 0.5) * 1.0;
  self.vy += (dy / dist) * away * 1.2 + (Math.random() - 0.5) * 1.0;
}

6. skill.js — Kỹ năng đặc biệt chạy mỗi frame

Nhận (self, enemy, api). Đây là nơi duy nhất có quyền gây damage đặc biệt, tạo phi tiêu, tạo vùng nổ, đổi trạng thái animation. Cooldown/thời điểm kích hoạt tự quản lý bằng cách lưu vào self.skillState (object tự do, bạn muốn lưu gì cũng được).

Mẫu buff tạm thời (tăng damage vũ khí có thời hạn)

if (!self.skillState) self.skillState = { cooldown: 0, active: 0 };
if (self.skillState.active > 0) {
  self.skillState.active--;
  self.weaponBoost = 2.0;
} else {
  self.weaponBoost = 1.0;
  if (self.skillState.cooldown > 0) {
    self.skillState.cooldown--;
  } else {
    self.skillState.active = 60;   // buff kéo dài 60 frame
    self.skillState.cooldown = 300; // cooldown 300 frame
  }
}

Mẫu phóng phi tiêu thẳng

if (!self.skillState) self.skillState = { cooldown: 0 };
if (self.skillState.cooldown > 0) {
  self.skillState.cooldown--;
} else {
  const dx = enemy.x - self.x, dy = enemy.y - self.y;
  const dist = Math.sqrt(dx*dx + dy*dy) || 1;
  const spawned = api.spawnProjectile({
    vx: (dx / dist) * 8,
    vy: (dy / dist) * 8,
    damage: 6,
    radius: 8,
    lifespan: 90
  });
  if (spawned) self.skillState.cooldown = 100;
}

Mẫu bắn CHÍNH vũ khí đang quay quanh thân mới

Khác với phi tiêu tự tạo ở trên (bay 1 vật thể mới), cách này bắn đi đúng cây vũ khí đang quay quanh thân bóng — thân bóng sẽ mất khả năng cận chiến cho tới khi vũ khí bay đủ 3 lần nảy tường và tự quay về. Cần phối hợp 2 file cùng lúc:

if (!self.skillState) self.skillState = { cooldown: 0 };
if (self.mainWeaponFlying) {
  // Vũ khí đang bay -> không bắn thêm, đợi nó tự về (đúng luật:
  // "đợi vũ khí chính bật 3 lần và quay về thì mới xài tiếp")
} else if (self.skillState.cooldown > 0) {
  self.skillState.cooldown--;
} else {
  const dx = enemy.x - self.x, dy = enemy.y - self.y;
  const dist = Math.sqrt(dx*dx + dy*dy) || 1;
  const spawned = api.spawnProjectile({
    vx: (dx / dist) * 7,
    vy: (dy / dist) * 7,
    damage: 15,        // damage riêng cho lúc bay (không nhất thiết = cận chiến)
    radius: 10,
    kind: "mainWeapon"  // <- bắn chính vũ khí, không phải vật thể mới
  });
  if (spawned) self.skillState.cooldown = 250;
}

// Khi vũ khí đang bay làm phi tiêu, thân bóng không còn gì quay quanh nữa
if (self.mainWeaponFlying) return null;

// Code vẽ vũ khí bình thường — dùng LẠI CHÍNH đoạn code này để vẽ hình
// dạng lúc bay (engine tự gọi lại weapon.js với self giả đặt tại vị trí
// phi tiêu để hình dạng lúc bay giống hệt lúc quay quanh thân)
self.weaponAngle = (self.weaponAngle || 0) + 0.12 * self.weaponBoost;
const len = 46, width = 10;
const tipX = self.x + Math.cos(self.weaponAngle) * len;
const tipY = self.y + Math.sin(self.weaponAngle) * len;
api.drawLine(self.x, self.y, tipX, tipY, "#c9d6e3", width);
api.drawCircle(tipX, tipY, width * 0.55, "#e8eef5");
return { tipX, tipY, hitRadius: width / 2 + 14 };

Mẫu vùng nổ hẹn giờ (xem thêm ví dụ đầy đủ ở mục 9)

if (!self.skillState) self.skillState = { cooldown: 0 };
if (self.skillState.cooldown > 0) {
  self.skillState.cooldown--;
} else {
  api.setAnimTag("cast");
  api.spawnZoneEffect({
    x: enemy.x, y: enemy.y,   // đánh dấu ngay vị trí địch lúc kích hoạt
    radius: 50,
    delay: 180,                // đợi 180 frame (~3 giây @ 60fps) rồi nổ
    damage: 35,
    damageMode: "once"
  });
  self.skillState.cooldown = 400;
}

7. anim.js — Animation chạy mỗi frame

Nhận (self, api). Trả về {col, row} — tọa độ frame trong lưới sprite muốn hiển thị ngay lúc này.

Animation chạy vòng lặp đơn giản (idle/di chuyển)

if (!self.animState) self.animState = { tick: 0 };
self.animState.tick++;
const cols = self.sprite ? self.sprite.cols : 1;
const totalFrames = cols * (self.sprite ? self.sprite.rows : 1);
const frameIndex = Math.floor(self.animState.tick / 8) % totalFrames;
return { col: frameIndex % cols, row: Math.floor(frameIndex / cols) };

Animation đổi theo trạng thái skill (đọc self.animTag)

// self.animTag tự động là "idle" bình thường, tự thành "hurt" khi vừa
// trúng đòn (12 frame), hoặc bất kỳ chuỗi nào skill.js đặt qua setAnimTag.
if (self.animTag === "hurt") {
  return { col: 3, row: 0 }; // frame nhăn mặt
}
if (self.animTag === "raise_hand") {
  return { col: 2, row: 0 }; // frame giơ tay ra hiệu
}
// Mặc định: animation idle chạy vòng lặp
if (!self.animState) self.animState = { tick: 0 };
self.animState.tick++;
const frameIndex = Math.floor(self.animState.tick / 10) % 2;
return { col: frameIndex, row: 0 };

8. Bảng tra cứu API đầy đủ

Tham số spawnProjectile(opts)

Phi tiêu tự động nảy tường như bi-a; sau đúng 3 lần nảy, tự bẻ hướng bay thẳng về chủ dù không set returnTo. Với kind:"mainWeapon": dù có bay trúng đối thủ giữa đường, vũ khí không biến mất — vẫn tiếp tục hành trình cho tới khi đủ 3 lần nảy tường rồi mới tự quay về; trong suốt thời gian đó thân bóng không có vũ khí nào để đánh cận chiến.

Tham số spawnZoneEffect(opts)

9. Ví dụ đầy đủ: "Lính Tên Lửa"

Minh họa cách kết hợp setAnimTag + spawnZoneEffect để tạo skill: khi kích hoạt, đổi hình sang tư thế giơ tay, đánh dấu vị trí đối thủ, đợi 3 giây rồi một quả tên lửa rơi xuống gây nổ diện rộng. Đây chỉ là ví dụ tham khảo — không có sẵn trong game, bạn cần tự tạo folder và sprite riêng nếu muốn dùng.

return null;

const dx = enemy.x - self.x, dy = enemy.y - self.y;
const dist = Math.sqrt(dx*dx + dy*dy) || 1;
const desiredDist = 200;
if (api.now % 20 === 0) {
  const away = dist < desiredDist ? -1 : 0.4;
  self.vx += (dx / dist) * away * 1.0 + (Math.random() - 0.5) * 0.8;
  self.vy += (dy / dist) * away * 1.0 + (Math.random() - 0.5) * 0.8;
}

if (!self.skillState) self.skillState = { cooldown: 0, raising: 0 };

if (self.skillState.raising > 0) {
  // Đang trong tư thế giơ tay (30 frame) trước khi thực sự đánh dấu mục tiêu
  api.setAnimTag("raise_hand");
  self.skillState.raising--;
  if (self.skillState.raising === 0) {
    api.spawnZoneEffect({
      x: enemy.x, y: enemy.y,     // chốt vị trí đối thủ NGAY lúc này
      radius: 55,
      delay: 180,                  // 180 frame ~ 3 giây (@ 60fps)
      damage: 35,
      damageMode: "once",
      color: "#ff5533"
    });
  }
} else if (self.skillState.cooldown > 0) {
  self.skillState.cooldown--;
} else {
  self.skillState.raising = 30;   // bắt đầu tư thế giơ tay
  self.skillState.cooldown = 500; // cooldown dài vì damage cao
}

if (self.animTag === "raise_hand") {
  return { col: 2, row: 0 }; // frame giơ tay trong sprite sheet
}
if (self.animTag === "hurt") {
  return { col: 3, row: 0 }; // frame trúng đòn (engine tự set, không cần gọi)
}
// idle mặc định: đi bộ tại chỗ, lặp giữa frame 0 và 1
if (!self.animState) self.animState = { tick: 0 };
self.animState.tick++;
const frameIndex = Math.floor(self.animState.tick / 12) % 2;
return { col: frameIndex, row: 0 };

{
  "cols": 4,
  "rows": 1,
  "maxHP": 180,
  "maxSpeed": 4.5,
  "baseDamage": 35,
  "color": "#5a7a4a",
  "skillName": "Không Kích",
  "skillDesc": "Giơ tay đánh dấu mục tiêu, 3 giây sau tên lửa rơi xuống gây 35 sát thương diện rộng."
}

10. Những gì KHÔNG thể thay đổi

Đây là phần cố định trong engine — áp dụng cho mọi bóng, kể cả bóng mới tạo, không code nào (weapon/ai/skill/anim) có thể ghi đè hay tắt được:

Điều này đảm bảo mọi bóng — dù skill có sáng tạo đến đâu — vẫn tuân theo cùng 1 luật chơi vật lý nền tảng, giữ cho trận đấu luôn công bằng và có thể đoán trước được ở cấp độ cơ bản nhất.