Documentation

This is the comprehensive technical reference for the LimeTree Adventure Engine. LimeTree is built for speed, portability, and ease of use, bridging the gap between raw text files and interactive experiences.

Project Status: v1.0 Production Ready.
LimeTree is a self-contained ecosystem. No external database or server logic is required to run a full-scale adventure.

The Manifesto

In an era of bloated game engines, LimeTree stands for radical simplicity. Our engine architecture is based on the following non-negotiable pillars:

  • Human Readable: Game logic should be understandable without a computer science degree.
  • Zero Installation: The player is a single HTML file. The game is a single ZIP.
  • Privacy First: No tracking, no cookies, no cloud. Everything happens on the user's machine.

The Parser Core

The core of LimeTree is an interpretative layer written in vanilla JavaScript. It does not compile; it reads. This allows for rapid prototyping where changes in the text file are reflected instantly upon reloading the ZIP.

Execution Order

1. ZIP Header Validation
2. Extraction of @start/!a.txt
3. Sanitation of Script Strings
4. Injection into DOM Elements
5. Event Listener Assignment for Buttons

Virtual File System (VFS)

LimeTree creates a temporary Virtual File System in the browser's memory. This is why you can reference images and scripts within the ZIP without hosting them on a server.

Memory Constraint: Since the VFS resides in RAM, keeping your ZIP files under 50MB is recommended for mobile compatibility.

Declarative Logic Syntax

The scripting within !a.txt is designed to be declarative. You define "what it is" rather than "how it happens."

// Global Scope Definition
self.label = "You are in the engine core.";
self.button1.text = "Initialize System";
self.button1.portal = portals.init_sequence;

// Optional: System Feedback
console.log("Portal Loaded Successfully.");

Portal Directory Rules

Portals are the "rooms" of your game. Each portal must follow the standard directory structure to be recognized by the VFS.

Naming Convention Required Description
@start YES The initial entry point of every LimeTree game.
!a.txt YES The logic file containing self.label and self.button assignments.
image.jpg NO Asset reference for visual portals (future support).

Termination Logic

The exitFromTheTree() function is a specialized native method. When called, it performs a secure wipe of the virtual memory and returns the DOM to its initial "Ready for Input" state.

Usage Scenario

// Use this for "Game Over" or "The End" portals
self.label = "The journey has concluded.";
self.button4.text = "Back to Menu";
self.button4.portal = exitFromTheTree();

Error Code Index

If the engine encounters a problem, it will display a specific error code. Refer to the table below for solutions.

  • ERR_NO_START: Folder @start not found in ZIP root.
  • ERR_LOGIC_NULL: !a.txt exists but contains no valid commands.
  • ERR_VFS_CORRUPT: The ZIP file is corrupted or protected by a password.
  • ERR_PORTAL_LOOP: A portal attempts to call itself without a trigger.