Caskara: A Data Engine for Hytale Mods

Caskara is a data engine built specifically for the modding ecosystem of Hytale. It combines the reliability of SQLite with the flexibility of JSON-style data structures, giving mod developers a fast and practical way to store and manage persistent data.

Instead of relying on external services or complex setup, Caskara runs locally alongside the mod. This makes it easy to integrate while keeping performance stable even when a server is handling large amounts of game events or player data.

⚠️ Beta Release

Caskara is currently in Beta.
It has been tested, but bugs or inconsistencies may still exist. Please report any issues you find.

📖 Read the Full API Documentation

📖 Read the Full Technical API

📦 Architecture Overview

Caskara uses a Shell & Core architecture:

• Shell → Database file (example: global.db, players.db)
• Core → Data type inside the shell (example: Quests, PlayerStats)

Flow (simplified)

Plugin Code → Caskara API → Shell Controller
↓
┌───────────────┐
│   Shells      │
│ global.db     │
│ players.db    │
└──────┬────────┘
↓
┌───────────────┐
│    Cores      │
│ Quests        │
│ Factions      │
│ PlayerStats   │
└───────────────┘

Internal:
LRU Cache ↔ JSON ↔ AES-256 ↔ SQLite

`

🏁 Beginner's Guide: Basic CRUD

1. Model your data

public class Quest {
    public String id;
    public String title;
    public boolean completed;
}

`

2. Basic Operations

Quest q = new Quest("Fire Dragon", false);
Caskara.save(q);

Quest loaded = Caskara.load("Fire Dragon", Quest.class);

List<Quest> allQuests = Caskara.list(Quest.class);

Caskara.delete("Fire Dragon", Quest.class);

🛡️ Advanced Features

ACID Transactions

Caskara.transaction(tx -> {
    Wallet p1 = tx.load("uuid1", Wallet.class);
    Wallet p2 = tx.load("uuid2", Wallet.class);

    p1.balance -= 100;
    p2.balance += 100;

    tx.save(p1);
    tx.save(p2);
});

Hooks & Validation

var core = Caskara.core(Player.class);

core.addValidator(p -> p.level > 0);

core.onAfterSave((id, p) ->
    Logger.info("Player " + p.name + " was saved.")
);

TTL & Soft Delete

Caskara.save(tempBuff, Duration.ofMinutes(30));

Caskara.softDelete("mod-123", ModData.class);
Caskara.restore("mod-123", ModData.class);

🔐 Encryption

Caskara.encrypt(SecretConfig.class, "your-super-secret-key");

Caskara.save(new SecretConfig("token", "xyz-123"));

⚙️ Technical Details

JSON Query Engine

Caskara.createIndex(Player.class, "stats.level");

Internal:

CREATE INDEX idx_player_level
ON elements(json_extract(json, '$.stats.level'))

Performance Metrics

var stats = Caskara.stats();

System.out.println("Cache Hit Rate: " + stats.getCacheHitRate() * 100 + "%");
System.out.println("Avg Latency: " + stats.getAverageQueryTimeMs() + "ms");

📊 Comparison

❌ When NOT to use

• Large files (images/videos)
• Complex relational data
• Multi-server shared DB