TempleOS and HolyC Comprehensive Guide

Table of Contents

1. What is TempleOS?
2. Installation
3. Basic Concepts
4. HolyC Programming Language
5. System Commands
6. File System
7. Graphics and Sprites
8. Your First Program
9. Games and Demos
10. Tips and Tricks

---

What is TempleOS?

TempleOS is a 64-bit, multi-tasking operating system developed single-handedly by Terry A. Davis. Developed between 2003-2013, this system stands out with its unique features:

Core Features

• Runs in 640x480, 16-color VGA graphics mode
• Uses a custom programming language called HolyC (similar to C/C++)
• Operates at Ring-0 level (no kernel-user separation)
• Completely open source - all source code is included
• Contains ~100,000 lines of code
• Works with JIT (Just-In-Time) compiler
• Simple memory management - no garbage collector

Philosophy

Terry Davis designed TempleOS as "God's Temple". The system was conceived as a tool for worship and programming. This is why it includes some unconventional features:

• Oracle (divination) system
• Biblical references
• Random word/number generator

---

Installation

Requirements

• Virtual Machine (recommended): VMware, VirtualBox, QEMU
• Physical Machine: x86-64 processor
• RAM: Minimum 512 MB (2 GB recommended)
• Disk: 500 MB

Installation with VirtualBox

1. Download ISO

   • Download the TempleOS ISO file from the official site or archive.org
   • Latest stable version is recommended

2. Create Virtual Machine

   Type: Other/Unknown (64-bit)
   RAM: 2048 MB
   Disk: 2 GB (VDI, dynamic)
   Video Memory: 16 MB
   

3. Settings

   • System → Processor → 2 CPUs recommended
   • Display → Graphics Controller → VBoxVGA
   • Storage → Add ISO file to IDE Controller

4. First Boot

   • Start the VM
   • It will boot from the ISO
   • Automatic installation will begin

Installation to Hard Disk

BootHDIns;  // Installs to hard disk
// The system will install after confirmation

⚠️ Warning: This command formats the virtual disk. Be careful when using on physical machines!

---

Basic Concepts

User Interface

TempleOS has an unconventional interface:

• Mixed graphics and text environment
• Everything is editable - the screen is a "document"
• Sprites and objects can be placed with the mouse
• Command line is everywhere

Terminal Usage

// Commands are typed directly
Dir;           // Directory listing
Cd("directory"); // Change directory
Type("file");   // Show file contents

Shortcuts

Window System

In TempleOS each task is its own window:

PopUp("Message here"); // Opens popup window
WinMax;                // Maximize window
WinToTop;              // Bring window to front

---

HolyC Programming Language

HolyC is a variation of the C language but has some differences.

Basic Syntax

// Variables
U8 number = 10;        // 8-bit unsigned integer
I64 bigNumber = 100;   // 64-bit signed integer
F64 decimal = 3.14;    // 64-bit float
U8 *text = "Hello";    // String (char pointer)

// Functions
U0 HelloWorld() {
    Print("Hello World!\n");
}

// Loops
I64 i;
for (i = 0; i < 10; i++)
    Print("%d\n", i);

// Conditionals
if (number > 5)
    Print("Big\n");
else
    Print("Small\n");

Data Types

I8   // 8-bit signed integer
U8   // 8-bit unsigned integer
I16  // 16-bit signed integer
U16  // 16-bit unsigned integer
I32  // 32-bit signed integer
U32  // 32-bit unsigned integer
I64  // 64-bit signed integer
U64  // 64-bit unsigned integer
F64  // 64-bit floating point
U0   // Void (function return type)

Differences from C

1. U0 is used instead of void
2. True/FALSE are capitalized
3. Classes are supported
4. Macros work differently

Input/Output

// Print to screen
Print("Number: %d\n", 42);
"%d number\n", 42;  // Shortcut

// User input
I64 number = GetI64("Enter a number: ");
U8 *text = GetStr("Enter text: ");

// Write to file
U8 *content = "Hello file!";
FileWrite("C:/Temp/test.txt", content, StrLen(content));

---

System Commands

File Management

Dir;                    // List files in current directory
Dir("C:/");            // List specific directory
Cd("directory_name");  // Change directory
Cd("..");              // Go to parent directory
Copy("source", "dest"); // Copy file
Del("file");           // Delete file
Move("old", "new");    // Move/rename file
MkDir("new_directory"); // Create folder

System Information

Dave;       // Reboot system
Exit;       // Close window
Help;       // Show help
Adam;       // Adam help system
MemReport;  // Memory report

Compiler and Editor

Ed("file.HC");        // Open file in editor
Type("file.HC");      // Show file contents
#include "file.HC"    // Include file (compile time)

---

File System

File Structure

TempleOS uses the RedSea file system:

• FAT32-like structure
• Maximum file size: 4 GB
• Disk partition: ISO9660 compatible
• Path separator: Forward slash / or backslash \

File Operations

// Read file
U8 *content = FileRead("C:/Temp/test.txt");
Print("%s", content);
Free(content); // Free memory

// Write file
U8 *text = "Test data";
FileWrite("C:/Temp/output.txt", text, StrLen(text));

// Check file existence
if (FileFind("C:/Temp/test.txt"))
    Print("File found\n");
else
    Print("File not found\n");

// File information
CDirEntry de;
if (FileFind("C:/Temp/test.txt", &de))
    Print("Size: %d bytes\n", de.size);

Directory Structure

C:/
├── Home/          // User files
├── Temp/          // Temporary files
├── Demo/          // Demo programs
├── Apps/          // Applications
└── Kernel/        // System files

---

Graphics and Sprites

Basic Graphics Functions

// Plot pixel
GrPlot(gr, x, y, color);

// Draw line
GrLine(gr, x1, y1, x2, y2, color);

// Rectangle
GrRect(gr, x1, y1, x2, y2, color);

// Circle
GrCircle(gr, x, y, radius, color);

// Draw text
GrText(gr, x, y, "Hello");

Colors

TempleOS uses 16 colors:

BLACK = 0
BLUE = 1
GREEN = 2
CYAN = 3
RED = 4
PURPLE = 5
BROWN = 6
LTGRAY = 7
DKGRAY = 8
LTBLUE = 9
LTGREEN = 10
LTCYAN = 11
LTRED = 12
LTPURPLE = 13
YELLOW = 14
WHITE = 15

Creating Sprites

// Open sprite editor
Sprite;  // Visual sprite editor

// Programmatic sprite
U8 sprite_data[8][8] = {
    {0,0,1,1,1,1,0,0},
    {0,1,1,1,1,1,1,0},
    {1,1,0,1,1,0,1,1},
    {1,1,1,1,1,1,1,1},
    {1,1,1,1,1,1,1,1},
    {0,1,1,0,0,1,1,0},
    {0,0,1,1,1,1,0,0},
    {0,0,0,0,0,0,0,0}
};

Animation

U0 AnimationExample() {
    I64 x = 0, y = 240;
    while (!CharScan) {  // Until key press
        GrClear;  // Clear screen
        GrCircle(gr, x, y, 10, RED);
        x = (x + 2) % 640;
        Sleep(20);  // Wait 20 ms
    }
}

---

Your First Program

Hello World

U0 HelloWorld() {
    "Hello, TempleOS World!\n";
}

HelloWorld;

Simple Calculator

U0 Calculator() {
    F64 num1, num2, result;
    U8 operation;
    
    num1 = GetF64("First number: ");
    num2 = GetF64("Second number: ");
    operation = GetChar("Operation (+, -, *, /): ");
    
    switch (operation) {
        case '+': result = num1 + num2; break;
        case '-': result = num1 - num2; break;
        case '*': result = num1 * num2; break;
        case '/': 
            if (num2 != 0)
                result = num1 / num2;
            else {
                "Error: Division by zero!\n";
                return;
            }
            break;
        default:
            "Invalid operation!\n";
            return;
    }
    
    "Result: %f\n", result;
}

Calculator;

Guessing Game

U0 GuessingGame() {
    I64 number, guess, attempts = 0;
    
    number = RandU16 % 100 + 1;  // Random number between 1-100
    
    "I'm thinking of a number between 1 and 100!\n";
    
    do {
        guess = GetI64("Your guess: ");
        attempts++;
        
        if (guess < number)
            "Try a larger number!\n";
        else if (guess > number)
            "Try a smaller number!\n";
        else
            "Congratulations! You got it in %d attempts!\n", attempts;
            
    } while (guess != number);
}

GuessingGame;

Saving to File and Running

1. Open editor: Ed("mygame.HC");
2. Write your code
3. Press F5 to compile and run
4. Or from command line: #include "mygame.HC"

---

Games and Demos

TempleOS includes many built-in demos and games:

Popular Games

// Aftershock - Platform game
#include "::/Apps/AfterShock/AfterShock.HC"

// BomberGolf - Golf game
#include "::/Apps/BomberGolf/BomberGolf.HC"

// Talons - Space combat game
#include "::/Apps/Talons/Talons.HC"

Demos

// 3D mesh demo
#include "::/Demo/Graphics/MeshDemo.HC"

// Sprite demo
#include "::/Demo/Graphics/SpriteDemo.HC"

// Sound demo
#include "::/Demo/Sound/SndDemo.HC"

Explore Yourself

Cd("::/Apps");
Dir;  // Show all applications
Cd("::/Demo");
Dir;  // Show all demos

---

Tips and Tricks

Performance

// Use frame buffer for fast graphics
CDC *dc = DCNew(640, 480);
// Graphics operations...
DCDel(dc);

// Avoid unnecessary memory allocation
// TempleOS has no garbage collector!
Free(ptr);  // After each allocation

Debugging

// Debug output
Print("Variable: %d\n", x);

// Adam help system
Adam("function_name");  // Info about function

// Breakpoint (simple)
GetChar;  // Wait for key press

Useful Commands

Man;           // Manual pages
Plain;         // Plain text mode
DocEd;         // Document editor
AutoComplete;  // Auto completion
TreeMake;      // Create project tree

Keyboard Shortcuts

• CTRL+ALT+X: Kill task
• CTRL+ALT+D: Document mode
• CTRL+ALT+G: Insert graphic sprite
• CTRL+ALT+S: Insert sound
• CTRL+ALT+N: New window

Learning Resources

1. Adam Help System: Built-in documentation

   Adam("Print");  // About Print function
   

2. Read Source Code: The entire system is open source

   Ed("::/Kernel/KMain.HC");  // Examine kernel
   

3. Study Demo Code

   Cd("::/Demo");
   Dir;
   

Common Errors

1. Compilation Error: Check syntax

   • Missing semicolon
   • Wrong variable types

2. Memory Error: Free allocated memory with Free()

3. File Not Found: Check path separators (/ or \)

Advanced Topics

// Multi-threading
U0 TaskFunction() {
    // Task code
}
Spawn(&TaskFunction);  // New thread

// Class definition
class MyClass {
    I64 number;
    U8 *text;
};

// Inline assembly
asm {
    MOV RAX, 42
    PUSH RAX
}

---

Important Notes

⚠️ Things to Keep in Mind:

1. Stability: TempleOS is an experimental project, crashes may occur
2. Backup: Regularly backup your important work
3. Network Support: TempleOS has no network support
4. Security: No security layer as it runs at Ring-0
5. Memory: Manual memory management is required

---

Conclusion

TempleOS offers a unique learning experience. Terry Davis's vision provides a different perspective from modern operating systems. Thanks to its simple design, it's a great platform to learn how operating system kernels work, how graphics are processed, and how programming languages are designed.

Happy coding!

---

Additional Resources

• Official Site: templeos.org (archived)
• GitHub Archive: github.com/cia-foundation/TempleOS
• Reddit Community: r/TempleOS_Official
• Video Tutorials: "TempleOS tutorial" on YouTube

Version Notes

This guide is based on the last stable version of TempleOS (V5.03).

---

Last Update: 2026 Author: TempleOS Community License: Public Domain