| --- |
| 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`. |
|
|
