README.md

---
language:
  - en
  - hi
tags:
  - godot
  - gdscript
  - 3d
  - mobile
  - android
  - modeling
  - sculpting
  - rigging
  - cloth-simulation
  - game-engine
license: mit
library_name: godot
pipeline_tag: other
---

# MonkeyStudio

**An open-source 3D creation studio for low-RAM (4 GB) Android phones**, built
with **Godot 4.x + GDScript**. Think of it as a foundation for a Blender-style
mobile tool: procedural modeling, sculpting, skeletal rigging, cloth/hair
simulation and keyframe animation — all designed around a memory architecture
that is meant to avoid Out-Of-Memory crashes on weak devices.

This repository contains the **full source code** and a **ready-to-install
debug APK**.

---

## Download the APK

The built app is included at:

```
build/MonkeyStudio.apk
```

| Property | Value |
|---|---|
| Package | `com.monkeycode.monkeystudio` |
| Version | `0.1.0` (versionCode 1) |
| Size | ~55 MB |
| Architectures | `arm64-v8a`, `armeabi-v7a` (32-bit + 64-bit ARM) |
| minSdk | 24 (Android 7.0) |
| targetSdk | 36 |
| Signing | Android Debug key (side-load only) |

Install on a phone:

```bash
adb install -r build/MonkeyStudio.apk
```

or copy the `.apk` to the phone and install it manually (enable
"Install from unknown sources"). This is a **debug-signed** build meant for
testing and side-loading, not for the Play Store.

---

## Honest scope note

Please read this before expecting a finished product.

- **No software is "100% bug-free."** Neither is this. Blender itself has had
  200+ contributors and thousands of bug fixes over 25+ years. Anyone who
  promises "guaranteed zero bugs" is not being truthful.
- **This is a working, tested foundation — not a feature-complete Blender
  clone.** A full mobile Blender is a multi-year, multi-developer effort. Each
  module here is real, runs, and is covered by an automated headless test
  suite (25 checks, all passing).
- The architecture is deliberately built so new tools can be added as
  `FeatureRegistry` entries without touching the memory core.

---

## What is implemented and tested

| Area | Status | Where |
|---|---|---|
| Memory budget, lazy load, LRU eviction | Done + tested | `scripts/core/memory_manager.gd` |
| Feature catalog / on-demand load & unload | Done + tested | `scripts/core/feature_registry.gd` |
| GPU mesh pooling (no GC spikes) | Done + tested | `scripts/core/mesh_pool.gd` |
| VRAM cost estimate + batched upload | Done + tested | `scripts/core/vertex_buffer_manager.gd` |
| Procedural meshes: cube, sphere, cylinder, plane, torus, icosphere, monkey head | Done + tested | `scripts/modules/mesh_gen.gd` |
| Sculpt brushes: draw, grab, pinch, smooth, flatten | Done + tested | `scripts/modules/sculpt.gd` |
| Skeleton3D builder + auto 4-influence weighting | Done + tested | `scripts/modules/rigging.gd` |
| Verlet mass-spring cloth + hair (gravity, wind) | Done + tested | `scripts/modules/simulation.gd` |
| Keyframe timeline (engine-native Animation) | Done + tested | `scripts/modules/timeline.gd` |
| Touch camera (orbit / pinch-zoom / pan) | Done | `scripts/studio/touch_camera.gd` |
| Dark material UI + collapsible panels + HUD | Done | `scripts/studio/studio_ui.gd` |
| App bootstrap / adaptive quality | Done | `scripts/studio/studio_main.gd` |

### Roadmap (not yet built)

UV unwrap, boolean operations, baking, OBJ/glTF/USD import-export, an undo
stack, dynamic geometry LOD, a wider brush set, and per-device performance
profiles.

---

## Memory architecture (the core idea)

A 4 GB phone gives an app roughly 1.2–1.5 GB before the OS starts killing it.
Blender-style tools are memory-hungry. The only way to offer many features
without OOM is to **never have them all resident at once**.

1. **`MemoryManager`** — owns a hard RAM budget (default 512 MB, auto-capped to
   1/8 of physical RAM). Assets are registered as `id -> path + cost`, *not*
   loaded. `acquire(id)` loads on first use; `release(id)` drops a reference.
   At zero references an asset becomes an eviction candidate. It evicts
   least-recently-used, zero-reference assets first — never one that is in use.
   It also polls `OS.get_memory_info()` and force-evicts when the OS reports
   < 128 MB free.
2. **`FeatureRegistry`** — a catalog of every tool as metadata only. `activate()`
   instantiates a module on demand; `deactivate()` destroys it and frees the
   RAM. "Close the tool, free the memory" is automatic.
3. **`MeshPool`** — recycles `ArrayMesh` objects; released meshes have their
   surfaces cleared (GPU buffers freed) but the object is reused, avoiding
   allocation churn.
4. **`VertexBufferManager`** — predicts RAM+VRAM cost before a mesh is built,
   and performs a *single* GPU upload per edit (mobile GPUs hate thousands of
   tiny buffer updates).
5. **Adaptive quality** — when FPS stays below 30, shadows are disabled first,
   then the simulation substep budget drops, keeping the frame budget bounded.

Full write-up: `docs/ARCHITECTURE.md`.

---

## About AI in this project

**Important and honest:** the current codebase contains **no AI / machine
learning / LLM component.** There is no model weights file, no neural network,
and nothing calls an AI API. It is a pure Godot engine application written in
GDScript.

The phrase "built with an AI coding assistant" refers to **how the code was
written** (an AI assistant helped author it), *not* to the app having AI
features at runtime.

If you want to add real AI capabilities, here are realistic options and how
they would fit this architecture:

| Idea | What it needs | Where it plugs in |
|---|---|---|
| Text-to-3D mesh generation | An ONNX/TFLite generative model (e.g. a small diffusion or point-cloud model) run on-device, or a cloud API | New `mesh_gen` backend that outputs the same `{verts, indices, uvs}` dictionary |
| Auto-retopology / auto-UV | A learned or classical algorithm | New feature module under `scripts/modules/` |
| AI texture generation | On-device Stable-Diffusion-lite or cloud API | Material assignment in `mesh_gen.gd` |
| Auto-rigging (skeleton from mesh) | A rig-prediction model | `rigging.gd` currently uses inverse-distance weights; a model could replace that heuristic |
| Prompt-based animation | Motion model / LLM driving keyframes | Feed results into `timeline.gd` `add_keyframe()` |

**Security note for any future AI integration:** never hardcode API keys. Read
them from the user's own project environment variables (for example
`os.get_environment("USER_LLM_API_KEY")` on desktop, or a settings screen on
Android) and ship a placeholder config. Keys must come from the user, not from
the build environment.

---

## Repository layout

```text
project.godot                Engine config (mobile renderer, landscape, 720p)
export_presets.cfg           Android APK export preset
scenes/main.tscn             App entry scene
scripts/
  core/                      MemoryManager, FeatureRegistry, MeshPool,
                             VertexBufferManager, StudioBus  (autoloads)
  modules/                   mesh_gen, sculpt, rigging, simulation, timeline
  studio/                    studio_main (bootstrap), studio_ui, touch_camera
  install_godot.sh           Linux installer (editor + export templates)
tests/self_test.tscn         Headless subsystem verification (25 checks)
docs/
  ARCHITECTURE.md            How the memory model and modules work
  BUILD_ANDROID.md           Full Godot + Android SDK + APK build guide
build/MonkeyStudio.apk       Ready-to-install debug APK
```

---

## Build it yourself

```bash
# 1. Install Godot + export templates (Debian/Ubuntu)
chmod +x scripts/install_godot.sh
./scripts/install_godot.sh

# 2. Reimport resources
godot --headless --import

# 3. Run the automated tests (exit 0 = all pass)
godot --headless res://tests/self_test.tscn

# 4. Open in the editor
godot --editor project.godot

# 5. Build an APK (needs Android SDK + JDK 17, see docs/BUILD_ANDROID.md)
mkdir -p build
godot --headless --export-debug "Android" build/MonkeyStudio.apk
```

Verified environment: **Godot 4.7.2-stable**, Debian 12, OpenJDK 17, Android
SDK build-tools 34.0.0.

---

## Testing

`tests/self_test.tscn` runs headless and exercises every subsystem: mesh
generation, all five sculpt brushes (vertices actually move), the skinning
channels, cloth falling under gravity, hair creation, and timeline keyframing.

```bash
godot --headless res://tests/self_test.tscn
# -> SELFTEST: ALL PASS  (25 PASS, 0 FAIL, exit 0)
```

---

## License

MIT. See `LICENSE`.