DiepAPI

<div align="center"> <img src="assets/diepAPI-logo.png" alt="diepAPI Logo" width="400"> <p><strong>A powerful JavaScript API for building bots, tools, and automation scripts for diep.io</strong></p>

</div>

---

What is diepAPI?

diepAPI is a comprehensive library that gives you programmatic access to the diep.io game. Build powerful bots and tools with just a few lines of code! Whether you want to create an AFK script, automate shape farming, or build advanced analytics tools, diepAPI makes it easy.

Key capabilities:

• 🎮 Real-time game state - Access player position, velocity, level, tank type, and more
• 🤖 Player control - Move, aim, shoot, and upgrade programmatically
• 👁️ Entity tracking - Track all visible players, shapes, and projectiles
• 🎨 Canvas overlays - Draw custom visualizations on top of the game
• ⚡ Event-driven - React to game events like spawning, leveling up, and frame updates
• 📘 TypeScript support - Full type definitions included

---

📦 Getting Started

Using diepAPI in Your Scripts (Recommended)

You don't need to install diepAPI separately! Just add a @require directive to your userscript, and your userscript manager will automatically load diepAPI for you.

Create a new userscript in Tampermonkey/Violentmonkey with:

// ==UserScript==
// @name         My Awesome Bot
// @description  My custom diep.io bot
// @match        https://diep.io/*
// @require      https://github.com/Cazka/diepAPI/releases/latest/download/diepAPI.user.js
// @grant        none
// ==/UserScript==

// diepAPI is automatically loaded and available here!
const { game, player } = diepAPI.apis;

game.on('ready', () => {
  console.log('Bot started!');
  player.spawn('MyBot');
});

That's it! The @require line automatically downloads and loads diepAPI before your script runs.

Requirements: Tampermonkey or Violentmonkey

---

Install Standalone (Optional)

If you want to experiment with diepAPI directly in the browser console without writing a script:

1. Install Tampermonkey or Violentmonkey
2. Download diepAPI.user.js from Releases
3. Install it in your userscript manager
4. Navigate to diep.io
5. Open browser console and use window.diepAPI

This method is mainly for testing and experimentation. For building bots, use the @require method above.

---

Building from Source

See the Building from Source section below.

---

🚀 Quick Start

Here's a complete, ready-to-use example. Copy this entire code block and create a new userscript in your userscript manager:

// ==UserScript==
// @name         Position Logger
// @description  Logs player position every frame
// @match        https://diep.io/*
// @require      https://github.com/Cazka/diepAPI/releases/latest/download/diepAPI.user.js
// @grant        none
// ==/UserScript==

// Access the APIs you need
const { game, player } = diepAPI.apis;

// Wait for the game to be ready
game.on('ready', () => {
  console.log('diepAPI is ready!');

  // Spawn with a custom name
  player.spawn('MyBot');
});

// Run code every frame
game.on('frame', () => {
  // Access player state
  console.log('Position:', player.position);
  console.log('Velocity:', player.velocity);
  console.log('Level:', player.level);
});

How to use:

1. Copy the code above
2. In Tampermonkey/Violentmonkey, click "Create new script"
3. Paste the code and save
4. Navigate to diep.io
5. Open browser console (F12) to see the logs

The @require directive automatically downloads diepAPI - no separate installation needed!

---

📚 Core Concepts

API Structure

diepAPI is organized into three main namespaces:

• diepAPI.apis - Core game APIs for accessing state and controlling the player

  • game, player, input, arena, camera, scaling, minimap, playerMovement, entityManager

• diepAPI.tools - Utility tools for drawing and visualization

  • overlay (canvas overlay), backgroundOverlay (background canvas), debugTool

• diepAPI.core - Core utilities like Vector math

Events

diepAPI uses an event-driven architecture. Subscribe to events to react to game state changes:

const { game, player } = diepAPI.apis;

// Game events
game.on('ready', () => console.log('Game is ready!'));
game.on('before_frame', () => console.log('Before frame'));
game.on('frame_start', () => console.log('Frame started'));
game.on('frame', () => console.log('New frame'));
game.on('frame_end', () => console.log('Frame ended'));
game.on('after_frame', () => console.log('After frame'));

// Player events
player.on('spawn', () => console.log('Player spawned'));
player.on('dead', () => console.log('Player died'));
player.on('level', (level) => console.log('Level up!', level));
player.on('tank', (tankType) => console.log('Tank changed:', tankType));

Remove event listeners with .off():

const handler = () => console.log('Frame');
game.on('frame', handler);
game.off('frame', handler); // Remove listener

Coordinate Systems

diepAPI works with three coordinate systems:

• Arena coordinates - Game world coordinates (origin at arena center)
• Canvas coordinates - High-DPI canvas rendering coordinates
• Screen coordinates - Browser viewport pixel coordinates

Convert between them using the scaling API:

const { scaling } = diepAPI.apis;

// Convert between coordinate systems
const arenaPos = scaling.toArenaPos(canvasPos);
const canvasPos = scaling.toCanvasPos(arenaPos);
const screenPos = scaling.canvasToScreen(canvasPos);
const canvasPos = scaling.screenToCanvas(screenPos);

---

💡 Complete Examples

Quick Reference

Choose an example based on your experience level:

| Example | Difficulty | What You'll Learn | Install | | -------------------------------------------------- | --------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Press O Script | 🟢 Beginner | Basic events, auto-spawn | | | AFK Script | 🟢 Beginner | Event handling, player control, movement | | | Shape Farmer | 🟡 Intermediate | Entity tracking, filtering, targeting | | | Safe Zone Keeper | 🟡 Intermediate | Position management, boundary logic, vectors | |

---

Beginner Examples

Beginner: Press O Script

The simplest possible bot - automatically opens the upgrade menu when you spawn and respawns when you die.

// ==UserScript==
// @name         Press O
// @description  best script
// @version      0.0.2
// @author       Cazka
// @match        https://diep.io/*
// @require      https://github.com/Cazka/diepAPI/releases/latest/download/diepAPI.user.js
// @icon         https://www.google.com/s2/favicons?domain=diep.io
// @grant        none
// ==/UserScript==

const { player } = window.diepAPI.apis;

player.on('spawn', async () => await player.keyPress('o'));
player.on('dead', async () => await player.spawn());

What you'll learn:

• Using player events (spawn, dead)
• Auto-spawning with player.spawn()
• Simulating key presses with player.keyPress()

---

Beginner: AFK Script

Keep your tank stationary at its current position. Press Q to toggle AFK mode on/off.

// ==UserScript==
// @name         AFK Script
// @description  press Q to activate AFK
// @version      0.0.5
// @author       Cazka
// @match        https://diep.io/*
// @require      https://github.com/Cazka/diepAPI/releases/latest/download/diepAPI.user.js
// @icon         https://www.google.com/s2/favicons?domain=diep.io
// @grant        none
// ==/UserScript==

const { Vector } = window.diepAPI.core;
const { player, game } = window.diepAPI.apis;

let afkActive = false;
let afkPosition;

// Toggle AFK mode with Q key
window.addEventListener('keydown', (e) => {
  if (e.code != 'KeyQ') return;

  // Toggle AFK state
  afkActive = !afkActive;

  // Enable/disable API control of playe