⚙️ CAAP (CPU As A Program)

🧠 A simple virtual CPU that executes custom assembly-like instructions inside Python.

CAAP is a lightweight interpreter that simulates a basic CPU.
It lets you run simple text-based instructions like SET and MOV to manipulate variables, just like a minimal processor.

---

🚀 Features

• 🧠 Simple CPU-like instruction system
• ⚡ Fast and lightweight (pure Python)
• 📦 No external dependencies
• 🧪 Easy to extend with new commands
• 🎮 Great for learning interpreters and CPU concepts
• 👀 CAAP provides a low-level memory system to read and write external process memory using powerful pointer-based access.
• 🔥 It supports multi-backend control (ctypes & pymem), dynamic pointer chains, and future tools like scanners and value freezing.

---

📥 Installation

pip install caap

---

🧑‍💻 Basic Usage

from caap import cpu

cpu = cpu()
@cpu.scommand("SET")
def function(a,b):
    cpu.varb[a] = b
@cpu.scommand("MOV")
def func(a,b):
    cpu.varb[a] = cpu.varb[b]

code = """
SET A, 10
SET B, 20
MOV C, A
"""

result = cpu.run(code)

print(cpu.varb)

---

📊 Output

{'A': 10, 'B': 20, 'C': 10}

---

👨‍💻 pointers usage

from caap import cpu

cpu = cpu()

f = cpu.pointers("pymem")

game = f.Pointer("minecraft.exe")

game.set_value("health123",value=999999,type="int")

print(game.get_value("health123"))

---

📊 Output

999999

---

📦 Changelog

All notable changes to this project will be documented in this section.

---

🚀 Version 0.0.5 ( latest )

✨ Added

• Added external process memory modification support (read/write to other applications)
• Added ctypes backend address auto-normalization (string → hex int)
• backends for external process memory modification ( pymem , ctypes )
• Improved memory write stability with pointer handling
• Better error handling for invalid memory addresses
• Added support for stable pointer-chain resolution, allowing memory values to stay accurate even after restarting the target program.

🛠️ Fixed

• Fixed crash when passing hex string addresses (e.g. "00D6FCDC")
• Fixed ctypes pointer conversion errors in write operations

⚡ Improved

• More stable memory backend behavior
• Cleaner internal address processing pipeline
• Reduced user-side input restrictions for addresses

🚀 Version 0.0.4

✨ Added

• Nothing

🛠️ Fixed

• package cannot find in package manager

⚡ Improved

• Nothing

---

🚀 Version 0.0.3

✨ Added

• Improved command parsing system
• Support for handling empty lines safely
• Better error messages for invalid syntax
• Adds Decorator Pattern
• Adds Debug Mode

🛠️ Fixed

• Fixed crash when command arguments are missing
• Fixed parsing issue causing incorrect split results
• Fixed IndexError when processing malformed input

⚡ Improved

• Cleaner execution flow inside run()
• More stable command execution system

---

🚀 Version 0.0.2

✨ Added

• Basic CPU system implementation
• SET and MOV commands
• Custom command registration system (scommand)

🛠️ Fixed

• Minor bugs in variable handling

---

🚀 Version 0.0.1

🎉 Initial Release

• Core structure of CAAP
• Basic execution engine
• Variable storage system

---

🧠 Notes

• This project is under active development
• Expect frequent updates and improvements
• Feedback and contributions are welcome 🚀

⚙️ Supported Instructions

Instruction	Description
SET A, value	Assign a value to a variable
MOV A, B	Copy value from variable B into A

---

🧠 How It Works

CAAP reads each line of text, splits it into commands, and executes it using an internal memory system (like CPU registers).

Each variable acts like a register inside a virtual CPU.

---

🔥 More Examples

📌 Example 1: Simple Math Storage

SET X, 5
SET Y, 15
MOV Z, X

Output:

{'X': 5, 'Y': 15, 'Z': 5}

---

📌 Example 2: Overwriting Values

SET A, 100
SET B, 50
MOV A, B

Output:

{'A': 50, 'B': 50}

---

🎮 Projects You Can Build With CAAP

🧮 1. Mini Calculator Engine

Use CAAP to simulate calculations step by step.

🧠 2. Simple AI Decision System

Use variables like memory states for decisions.

🎮 3. Text-Based Game Engine

Build HP systems, inventory, and battle logic.

⚙️ 4. CPU Simulation Learning Tool

Teach how CPUs work (registers, memory, execution).

🧪 5. Custom Language Experiments

Use CAAP as base for your own scripting language.

---

🧩 Roadmap

• [✔️] ADD support (A + B)
• [✔️] PRINT instruction
• [✔️] IF conditions
• [✔️] LOOP / JMP support
• [✔️] Error handling improvements
• [✔️] Debug mode (step-by-step execution)

---

🤝 Contributing

Feel free to:

• Add new instructions
• Improve execution engine
• Suggest optimizations

---

📄 License

This project is licensed under Apache License 2.0

---

🧠 Author

Built with ⚙️ and creativity by tamimdevlopment

---

🔥 Final Note

CAAP is not just a tool —
it’s a virtual CPU inside Python 🧠⚡