TracerKit Pro Documentation

Welcome to the official documentation for TracerKit Pro. This engine is a professional-grade suite for building high-quality kids' tracing and connect-the-dots games using Phaser 3 and TypeScript.

Core Highlights

• Universal Engine: Supports both classic tracing and sequential connect-the-dots.
• Visual Studio: Design and edit levels in-browser with zero coding required.
• Dynamic Theming: Fully customizable UI and gameplay visuals with real-time feedback.
• Enterprise Ready: Secure admin authentication and robust asset management.

Starter Game Packs

TracerKit Pro comes bundled with three professionally designed game packs to get you started immediately:

System Requirements

Installation Guide

Follow the specific guide below depending on whether you are setting up locally for development or deploying to a live server.

Local Development Setup

Use these steps for quick setup on your local machine to start designing levels.

1. Extract the tracerkit-pro-v1.0.0.zip file.
2. Terminal: Open your terminal and navigate to the folder:

   cd tracerkit-pro

3. Dependencies: Install the required modules:

   npm install

4. Configuration: Rename the .env.example file to .env and update the values as needed (see below).
5. Run: Start the engine:

   npm run server

Production Server Setup

Follow these steps to deploy to a live environment (e.g., VPS or cPanel).

1. Upload: Upload tracerkit-pro-v1.0.0.zip to your server.
2. Extract: Extract into your application root.
3. Environment: Rename .env.example to .env (or set variables in your cloud dashboard).
4. Build: Run npm install then npm run build.
5. Start: Use a process manager like PM2 to run npm start.

Environment Configuration (.env)

Your .env file manages security and server settings. Fill it with these values:

# 🌐 Server Configuration
PORT=3001

# 🔐 Security - IMPORTANT: Change this in production!
COOKIE_SECRET=8e2c4a9b1d5f3h7j0k6m9p2r5s8v1x4z7w0y3b6n9q2t5w8z1c4f7i0l3o6r9u2x

# 🍪 Authentication
AUTH_COOKIE_NAME=game_admin_auth

# 🛑 Rate Limiting (Brute-force protection)
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

First-Time Setup

When you first run the server, it detects that no admin account exists. You will be automatically redirected to the Setup Wizard.

TracerKit Pro Setup Wizard

Enter your chosen username and a strong password. Once submitted, the engine creates an admin-secret.json file and hashes your password using bcrypt.

Admin Dashboard

The Admin Dashboard is the nerve center of your game engine. Here you can create "Game Packs" (folders containing specific game themes like "Animals" or "Numbers").

Admin Dashboard Overview

Creating Your First Pack

Simply enter a Game ID (alpha-numeric) and a title. Choose a starting theme preset and click "Create Pack". The engine will generate the necessary file structure automatically.

Setting a Default Game

TracerKit Pro allows you to set a Default Game. When visitors load the root URL of your site, they will be automatically redirected to this game pack. Click the Green Star (⭐) button on any game card in the dashboard to set it as the default pack instantly.

Importing & Exporting Packs

TracerKit Pro makes it easy to backup your work or move game packs between different servers.

• Exporting: Click the Export (📥) icon on any game card to download a portable .zip file containing all levels, assets, and configurations for that pack.
• Importing: Use the Import Zone at the bottom of the dashboard. You can drag and drop an exported .zip file or click to browse.

Level Design Studio

The heart of TracerKit Pro is the Level Design Studio. This powerful, browser-based editor allows you to create complex tracing paths with zero coding. You can draw paths, place nodes, add audio triggers, and customize animations directly on the canvas.

Editor Workspace Overview

The Level Editor follows a professional workspace layout designed for efficiency:

TracerKit Pro Designer Workspace

The Main Toolbar

The toolbar at the top provides all the tools needed to construct and refine your tracing logic.

Standard Design Toolbar

Right Sidebar: Level & Assets

Configure how each specific level behaves and looks.

Advanced Level Configuration

• 📋 Level Info: Change the display name and toggle "Show All Paths at Once" (if off, paths appear sequentially as the user finishes them).
• 🎨 Assets:
  • Background: Set a reference image. Use Scale and Opacity to match your guide.
  • Color Reveal Mode: If checked, the background starts B/W and "reveals" color as the user traces.
  • Visibility: Choose if the background is Always Visible, Editor Only, or only appears On Completion.
  • Reward Image: The custom "completion" graphic that pops up when a level is finished.
• 🔊 Audio:
  • Intro: Custom VO that plays when the level starts (e.g., "Trace the letter A").
  • Completion: Custom sound or VO for the reward moment.

Contextual Properties

Clicking on a path or a node reveals specific floating toolbars for deeper control.

Selected Path Options

When you select a path, a floating menu appears with advanced manipulation tools:

Floating Path Properties Toolbar

• Markers: Toggle Start/End point indicators on the path. When enabled, a green circle marks the starting point and a red circle marks the ending point, helping players identify where to begin and finish tracing.
• Numbers: Toggle sequence numbers along the path. Displays numbered labels at each stop point to guide the player through the correct tracing order.
• Move Up: Move the selected path higher in the drawing order, changing which path the player traces first.
• Move Down: Move the selected path lower in the drawing order.
• Reverse Direction: Swap the start and end points of a path, reversing the tracing direction.
• Flip Horizontal: Mirror the selected path along the horizontal axis.
• Flip Vertical: Mirror the selected path along the vertical axis.
• Duplicate (D): Create an exact copy of the selected path(s), preserving all nodes and settings.
• Group (Ctrl+G): Combine multiple selected paths into a single logical group for simultaneous moving or mirroring.
• Ungroup (Ctrl+Shift+G): Separate a grouped set of paths back into individual elements.
• Delete Path (Delete / Backspace): Remove the selected path from the level.
• Clear All Paths: Reset the entire level by removing all paths. Use the ⚠️ icon to confirm and start over.

Selected Node Options (Nodes)

When editing a specific path node, use the floating Node Toolbar to:

Floating Node Properties Toolbar

• Stop Points: Defines where numbers appear on the path. In Connect Dot mode, these also act as mandatory checkpoints where the user must stop and start again (useful for multi-stroke shapes).
• Smooth/Sharp: Toggle between curved segments and sharp angles.
• Delete Node: Remove a specific point without deleting the whole path.

Keyboard Shortcuts

Efficiency is key. Use these shortcuts to speed up your design workflow:

How to Play

Once you've published your levels, players can interact with them using a simple touch or mouse interface. The engine handles all the complex logic of following paths, detecting errors, and triggering rewards.

1. Standard Tracing Mode

In this mode, players must trace along the logic path. The engine enforces boundaries and direction.

Standard Tracing Gameplay

2. Connect the Dots Mode

In this mode, numbers or indicators guide the player to tap/click points in sequence (1 → 2 → 3).

Connect the Dots Gameplay

SVG Path Import

Importing complex shapes from vector software is easy. TracerKit Pro supports standard SVG path data.

1. Click the SVG Import button in the editor toolbar.
2. Select your .svg file from your computer to import it directly onto the canvas.

Themes & Visuals

Change the entire mood of your game with the Dynamic Theming system. Each game pack can have its own unique personality.

Visual Customization

Built-in Presets

Comes with 5 professionally designed presets: Dark Indigo, Dark Emerald, Dark Rose, Light Classic, and Light Warm. A Custom option is also available for total control over branding.

Audio Configuration

Engagement in kids' games relies heavily on audio feedback. TracerKit Pro provides 7 dedicated global audio slots.

Game Mode Settings

Fine-tune the difficulty and behavior of each game pack.

Tracing Settings

Admin General Settings Panel

• Toddler Mode: When enabled, the trace line automatically follows the path. Ideal for younger players.
• Path Precision: Adjust the tolerance (10px to 80px). Strict mode requires perfect tracing; loose mode is more forgiving.

Connect the Dots Settings

Connect the Dots Settings Panel

• Dot Hit Radius: Adjust how close the user needs to get to a dot to trigger a connection.

Universal Display Options

Universal Display Settings Panel

• Level Card Mode Menu Only: Choose between showing initials (A, B, C) or numbers (1, 2, 3) on the level selection cards.
• Follow Path Connect Only: When enabled, the line snaps to the predefined path for a smoother experience.
• Progressive Dots Connect Only: Reveal dots one at a time as the player progresses, instead of showing all at once.
• Direction Arrow Both Modes: Shows a direction arrow on the start marker (Trace) or active dot (Connect) to guide movement.
• Start/End Circles Trace Only: Shows markers for the first and last points of a path to indicate where to begin and finish.
• Point Numbers Both Modes: Displays sequence numbers (1, 2, 3...) on each path point to guide the movement order.
• Guide Line Trace Only: Shows a visible "neon" guide path for the user to follow.
• Background Effects Both Modes: Toggles the animated particle effects (like stars) within the gameplay area.
• Path Progress Dots Both Modes: Shows progress indicators at the bottom (●○○) for levels with multiple paths.

Choosing a Hosting Method

Depending on your needs, you can host the full game engine or just the published game. Use the comparison below to choose the best method for your project.

Managed Cloud Hosting (Recommended)

Managed platforms are the easiest way to deploy TracerKit Pro. They handle SSL, scaling, and automatic deployments from GitHub.

Deploy to Railway / Render

1. Push your project to a private GitHub repository.
2. Connect your repository to Railway or Render.
3. Add your COOKIE_SECRET in the environment variables.
4. The engine will automatically run npm build and start the server.

Vercel Deployment

Ideal for quick previews or hosting the static game front-end.

1. Push your project to a private GitHub repository.
2. Import your repository to Vercel.
3. Add your COOKIE_SECRET in the **Environment Variables** tab.
4. Set **Framework Preset** to Other.
5. Set **Build Command** to npm run build.
6. Set **Output Directory** to dist.

Terminal-Based Setup (VPS / SSH)

For developers using a VPS (DigitalOcean, Ubuntu, AWS), follow these terminal commands to get running.

1. Clone and Install

git clone [your-repo-url]
npm install
npm run build

2. Environment Setup

Create a .env file in the root directory and add your secret key:

COOKIE_SECRET=your_very_secure_random_string_here

2. Process Management (PM2)

Use PM2 to keep the app running forever, even after a server crash.

# Install PM2
npm install -g pm2

# Start the application
pm2 start app.js --name tracerkit

# Ensure it starts on reboot
pm2 startup
pm2 save

3. Nginx Reverse Proxy

To serve your app on port 80/443, use this Nginx block:

location / {
    proxy_pass http://localhost:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

cPanel GUI Setup (Shared Hosting)

If your host provides the "Setup Node.js App" module in cPanel, follow these precise steps.

Setup Steps:

1. Upload the ZIP of your project and extract it in your Application Root.
2. Open cPanel > Setup Node.js App and click "Create Application".
3. Enter the details from the box above and click "Create Application".
4. Create your .env file in the app root with COOKIE_SECRET=your_secret.
5. Scroll down and click "Run NPM Install".
6. Click "Run JS Script" and select build to compile the engine.
7. Restart the application using the "Restart" button at the top.

Static Hosting (Game Only)

If you prefer to host only the final game (without the Admin Panel) on platforms like GitHub Pages, Netlify, or Vercel:

1. Run npm run build locally.
2. Copy your game folders from public/assets/games/ into dist/assets/games/.
3. Upload the entire dist/ folder to your web host.

How to Manage Your Project

Managing TracerKit Pro is designed to be seamless for both developers and non-technical administrators.

Daily Management Flow

1. Access the Dashboard: Log in at /admin to view your packs.
2. Create New Content: Use the "Create Pack" button for new themes.
3. Design Levels: Enter the Editor to draw paths or import SVGs.
4. Update Visuals: Use the "Settings" icon in the dashboard to change theme presets or colors instantly.

Updating the Engine

If you are using the full Node.js installation with GitHub/PM2:

# On your local machine or server
git pull origin main
npm install
npm run build

File Structure Explainer

A quick overview of the key files and directories in your project:

Source Code & Customization

For developers looking to extend the engine beyond the dashboard:

Core Logic Files

• Tracing Logic: src/game/mechanics/TracingController.ts (Handles path following and error detection).
• Gameplay Scene: src/game/GameScene.ts (Orchestrates level state, timers, and rewards).
• Level Selection: src/scenes/MenuScene.ts (Handles the pack/level choice screens).
• Data Handling: src/classes/LevelManager.ts (Handles loading/saving of pack data).
• Global Constants: src/GameConstants.ts (Change base resolution or grid settings).
• Theme Config: public/admin.js (Edit THEME_PRESETS to add your own dashboard designs).

Frequently Asked Questions

How do I update an existing Game Pack?

Simply click the "Edit" button on the dashboard to enter the Level Design Studio. Change any path or setting and it will save instantly.

Can I host this on my own private server?

Absolutely. You own the code. As long as the server has Node.js 18+, you can host it anywhere (VPS, Dedicated, or Shared with Node support).

Do I need to pay for hosting?

You can start for free on platforms like Railway or Render. For high traffic, you may eventually need a paid tier (usually $5-$10/mo).

Is the Setup Wizard secure?

Yes. It is programmed to run only once. Once your credentials are saved in admin-secret.json, the setup routes are permanently locked for security.

Troubleshooting Common Issues

Technical Support

We provide comprehensive support for all buyers. If you encounter any issues:

• Email: studiosupershark@gmail.com
• Include your: CodeCanyon Purchase Code