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:

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

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

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

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

---

License

MIT. See LICENSE.