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