Blender docs update

marwie · marwie · commit 9c24b9906855 · 2026-05-06T22:57:09.000+07:00
diff --git a/documentation/blender/components.md b/documentation/blender/components.md
@@ -74,10 +74,10 @@ Hover over any property to see its description.
 - `HoverAnimation` - Plays animation on pointer hover enter/exit events
 - `ScrollFollow` - Move objects based on scroll position
 - `EverywhereActions` - Trigger actions on various events (click, hover, collision, etc.)
+- [Learn more about interactivity →](/docs/how-to-guides/scripting/)
 
 **UI & UX:**
 - `Button` - Interactive buttons
-- `Canvas` - UI container
 
 **Multimedia:**
 - `VideoPlayer` - Play video files and streams
diff --git a/documentation/blender/environment.md b/documentation/blender/environment.md
@@ -0,0 +1,91 @@
+---
+title: Environment Lighting in Blender
+description: Set up environment lighting and skyboxes in Blender for the web — with automatic compression for fast loading
+---
+
+# Environment Lighting
+
+Set up environment lighting and skyboxes in Blender and export them to the web. Use any HDRI you want — Needle Engine automatically compresses it for fast loading and low memory usage.
+
+<video-embed limit_height max_height="300px" src="/docs/blender/environment.mp4" />
+
+---
+
+## Quick Start
+
+### Step 1: Assign an Environment Map
+
+1. Open **Viewport Shading** options (top right of the 3D viewport)
+2. Assign an HDRI / EXR cubemap
+3. Set `World Opacity` to **1** to make the skybox visible in the browser
+
+![Environment settings](/blender/environment.webp "2x")
+
+### Step 2: Use a Custom HDRI
+
+You can use any `.exr` or `.hdr` file — including large, high-resolution environment maps. Needle Engine takes care of compressing them for you during the build.
+
+<video-embed limit_height max_height="300px" src="/docs/blender/custom_hdri.mp4" />
+
+**Where to find free HDRIs:**
+- [Needle HDR Library](https://cloud.needle.tools/hdris) — Free, ready-to-use environments
+- [Poly Haven](https://polyhaven.com/hdris) — Hundreds of free CC0 HDRIs
+- [ambientCG](https://ambientcg.com/) — Free PBR materials and HDRIs
+
+---
+
+## Automatic Compression (FastHDR)
+
+You don't need to worry about environment map file sizes. When you **build your project** or **deploy to Needle Cloud**, Needle Engine automatically converts your environment maps into the [FastHDR](/docs/fasthdr) format. This means:
+
+- **Use any size** — 2K, 4K, or larger HDRIs all work great
+- **Automatic compression** — files get dramatically smaller (e.g. a 21 MB EXR becomes ~7 MB)
+- **Fast loading** — environments load in milliseconds instead of seconds
+- **Low memory usage** — uses up to 21x less GPU memory than raw EXR
+- **Same visual quality** — your lighting and reflections look identical
+
+This all happens behind the scenes during the build step — no manual work required.
+
+:::tip Preview compressed results locally
+Want to see how your scene looks with compression applied? Enable **Auto Compress** in the Needle Engine dropdown above the viewport. This gives you a local preview of the optimized result.
+:::
+
+---
+
+## Environment Camera
+
+By default, the environment map is used for both **lighting** (reflections and ambient light) and the **background** (the visible skybox).
+
+You can control the background appearance separately using the environment camera settings.
+
+![Environment camera settings](/blender/environment-camera.webp "2x")
+
+---
+
+## Tips
+
+**Quality:**
+- Higher-resolution HDRIs (4K+) give sharper reflections, especially on glossy surfaces
+- FastHDR compression preserves quality — don't downscale your source files
+
+**Performance:**
+- FastHDR environments load fast even on mobile devices and low-end hardware
+- If you don't need a visible skybox, you can still use an HDRI for lighting only by setting `World Opacity` to **0**
+
+**Troubleshooting:**
+- If colors look off, check your [Color Management settings](/docs/blender/#fix-color-management) — set `View` to **Standard**
+- If your scene has a greenish tint after building, see the [FAQ](/docs/reference/faq#why-does-my-blender-scene-have-a-green-tint-or-different-color-after-building-deploying-to-needle-cloud)
+
+---
+
+## Next Steps
+
+- **[FastHDR Deep Dive](/docs/fasthdr)** — Learn more about how environment compression works
+- **[Lightmapping](/docs/blender/lightmapping)** — Combine environment lighting with baked lightmaps
+- **[Optimization Guide](/docs/how-to-guides/optimization/)** — More ways to optimize your scenes for the web
+
+---
+
+**Need Help?**
+- [Discord Community](https://discord.needle.tools) - Ask questions about environment setup
+- [Forum](https://forum.needle.tools) - Share your projects and get feedback
diff --git a/documentation/blender/index.md b/documentation/blender/index.md
@@ -106,13 +106,29 @@ Download and **open any sample `.blend` file** in Blender. These samples show wh
 When you save your `.blend` file, Needle Engine automatically re-exports your scene and refreshes the browser. This hot reload makes iteration super fast!
 :::
 
-:::tip AI for Blender
-Needle already lets you use AI with Blender. Connect Claude, Copilot, Cursor, or OpenAI/Codex through Needle MCP to search your scene hierarchy, inspect selected objects, materials, and components, read project context, and even select objects in Blender. You can also launch Needle Cloud AI directly from Blender with the built-in `Ask AI about Project` action. [Learn more about Needle MCP →](/docs/ai/needle-mcp-server)
+:::tip AI-Assisted Workflow
+Need help with Needle Engine while working in Blender? Connect AI coding assistants like Claude, Copilot, or Cursor through Needle MCP — they can search your scene hierarchy, inspect objects and materials, read project context, and help you write components. You can also use the built-in `Ask AI about Project` action to get answers directly in Blender. [Learn more about Needle MCP →](/docs/ai/needle-mcp-server)
 :::
 
 ---
 
-## Step 3: Add Basic Interactivity
+## Step 3: Set Up Environment Lighting
+
+Your HDRI environment is automatically exported and used for lighting — objects in your scene will reflect it and receive ambient light from it. The visible background is separate: it can show the skybox or render as a solid color.
+
+**To set up your environment:**
+1. Open **Viewport Shading** options (top right of 3D viewport)
+2. Assign an HDRI cubemap
+3. Optionally, set `World Opacity` to **1** to also show it as the background skybox
+   <video-embed limit_height max_height="300px" src="/docs/blender/environment.mp4" />
+
+**✓ Checkpoint:** Save and check the browser — your scene should now have environment lighting (and a visible skybox if you set World Opacity to 1)!
+
+**[Learn more about environment lighting →](/docs/blender/environment)** — custom HDRIs, automatic compression for fast loading, and more.
+
+---
+
+## Step 4: Add Basic Interactivity
 
 Now let's add camera controls so users can explore your scene.
 
@@ -144,15 +160,10 @@ Components are reusable behaviors you add to objects. Needle Engine includes 100
 
 ---
 
-## Step 4: Configure Essential Settings
-
-Before going further, let's fix two common issues.
-
-### Fix Color Management
+## Step 5: Set Up Color Management
 
-By default, Blender uses `Filmic` which makes colors look different in the browser.
+By default, Blender uses `Filmic` which makes colors look different in the browser. Switch to `Standard` so what you see in Blender matches the web output.
 
-**To fix:**
 1. Go to **Render Properties** tab
 2. Find **Color Management** section
 3. Set `View` to **Standard**
@@ -161,24 +172,6 @@ By default, Blender uses `Filmic` which makes colors look different in the brows
 
 **✓ Checkpoint:** Colors now match between Blender and the web!
 
-### Setup Environment Lighting
-
-Your HDRI environment exports automatically, but you need to make it visible.
-
-**To show skybox:**
-1. Open **Viewport Shading** options (top right of 3D viewport)
-2. Assign an HDRI cubemap
-3. Set `World Opacity` to **1**
-   <video-embed limit_height max_height="300px" src="/docs/blender/environment.mp4" />
-
-**✓ Checkpoint:** Save and see your skybox appear in the browser!
-
-:::tip Fast environment maps — use any size you want
-You can use large, high-quality EXR environment maps without worrying about file size or loading speed. When you build your project or deploy to Needle Cloud, Needle Engine automatically compresses your environment into the [FastHDR](/docs/fasthdr) format — making it dramatically smaller and faster to load while keeping the same visual quality. This happens behind the scenes, no extra steps needed.
-
-Want to preview the compressed result locally? Enable **Auto Compress** in the Needle Engine dropdown above the viewport.
-:::
-
 ---
 
 ## What You've Learned
@@ -195,66 +188,16 @@ Your Blender scenes are now running on the web with hot reload!
 
 ## Next Steps
 
-### Continue Learning (Tutorials)
-
 **[For Blender Artists →](/docs/tutorials/fundamentals/for-blender-artists)**
-Comprehensive guide for 3D artists covering what you can create without code, workflow tips, and when you might want scripting.
-
-**[TypeScript Essentials →](/docs/tutorials/fundamentals/typescript-essentials)**
-Learn TypeScript basics to create custom interactive behaviors.
-
----
-
-### Add More Interactivity (How-To Guides)
-
-Now that you have the basics, explore specific features:
-
-**[Animation Workflows →](/docs/blender/animation)**
-Learn all animation methods: simple Animation component, AnimatorController state machines, and PlayableDirector timeline export.
-
-**[Components Guide →](/docs/blender/components)**
-Master the 100+ built-in components and learn to create your own custom TypeScript components.
-
-**[Lightmapping →](/docs/blender/lightmapping)**
-Bake photorealistic lighting for stunning visuals with great performance.
-
-**[Use Physics →](/docs/how-to-guides/scripting/use-physics)**
-Add rigidbodies, colliders, forces, and raycasting — built-in Rapier physics, no setup needed.
-
-**[Add Multiplayer →](/docs/how-to-guides/networking/)**
-Real-time networking with voice chat, synchronized state, and zero server configuration.
-
-**[Optimization & Progressive Loading →](/docs/how-to-guides/optimization/)**
-Production builds automatically generate mesh LODs, texture LODs, and apply compression — your scenes load instantly and stream in detail on demand. You can override compression format, max size, and LOD settings per texture in **Properties → Material tab → Needle Material Settings**.
-
-**[Deploy Your Project →](/docs/how-to-guides/deployment/)**
-Publish your interactive scene to the web for everyone to see.
-
-**[Enable WebXR →](/docs/how-to-guides/xr/)**
-Add VR and AR support to your scenes.
-
----
-
-### Look Things Up (Reference)
-
-**[Component Catalog →](/docs/reference/components)**
-Browse all 100+ built-in components with descriptions and settings.
-
-**[API Documentation →](https://engine.needle.tools/docs/api/)**
-Complete TypeScript API reference for advanced development.
-
-**[FAQ →](/docs/reference/faq)**
-Common questions and troubleshooting.
-
----
-
-### Get Inspired
-
-**[Sample Projects →](https://engine.needle.tools/samples)**
-Explore interactive examples to see what's possible.
-
-**[Download More Samples →](https://engine.needle.tools/downloads/blender/download-samples)**
-Get working `.blend` files to learn from.
+Comprehensive guide covering what you can create without code, workflow tips, and when you might want scripting.
+
+- [Environment Lighting →](/docs/blender/environment) — custom HDRIs, skybox settings, and automatic compression
+- [Animation →](/docs/blender/animation) — playback, state machines, and timeline export
+- [Components →](/docs/blender/components) — 100+ built-in behaviors and creating your own
+- [Lightmapping →](/docs/blender/lightmapping) — baked lighting for stunning visuals with great performance
+- [Deploy Your Project →](/docs/how-to-guides/deployment/) — publish to Needle Cloud or self-host
+- [Sample Projects →](https://engine.needle.tools/samples) — interactive examples to learn from
+- [FAQ →](/docs/reference/faq) — common questions and troubleshooting
 
 ---
 
diff --git a/documentation/tutorials/fundamentals/for-blender-artists.md b/documentation/tutorials/fundamentals/for-blender-artists.md
@@ -262,82 +262,13 @@ There's a friendly Discord community, extensive documentation, video tutorials,
 
 ---
 
-## Getting Started
-
-Ready to bring your 3D art to the web?
-
-### Installation (5 minutes)
-
-1. **Install Blender Add-on**
-   - [Download Needle Engine for Blender](https://engine.needle.tools/downloads/blender?utm_source=needle_docs&utm_content=getting_started)
-   - Install like any Blender add-on
-   - Activate in Preferences
-
-2. **Download Sample Projects**
-   - [Download Blender Samples](https://engine.needle.tools/downloads/blender/download-samples?utm_source=needle_docs&utm_content=blender)
-   - Open sample .blend files to see working examples
-   - Modify and experiment!
-
-3. **Start Creating**
-   - Begin with a simple scene
-   - Add Needle components from the side panel
-   - Click "Play in Browser" to preview
-
-:::tip Start Small
-Don't start with your most complex scene. Begin with something simple to learn the workflow, then level up!
-:::
-
-### Learning Resources
-
-**For Visual Learners:**
-- [Video Tutorials](https://www.youtube.com/@needle-tools) - Step-by-step guides
-- [Sample Projects](https://engine.needle.tools/samples) - Explore working examples
-- [Live Demos](https://samples.needle.tools/#showcase) - See what's possible
-
-**For Reading:**
-- [Blender Integration Guide](/docs/blender/) - Complete Blender workflow
-- [Component Reference](/docs/reference/components) - All built-in components
-- [How-To Guides](/docs/how-to-guides/) - Specific tasks
-
-**Community:**
-- [Discord Community](https://discord.needle.tools) - Ask questions, share work
-- [Forum](https://forum.needle.tools) - Discussions and examples
-- [Samples & Showcase](https://samples.needle.tools/#showcase) - Get inspired
-
----
-
-## Inspiration: What Will You Create?
-
-Needle Engine gives you **superpowers** as a 3D artist:
-
-- 🎨 Your art becomes **interactive and alive**
-- 🌐 Reaches **anyone, anywhere, instantly**
-- 📱 Works on **every device automatically**
-- 🥽 Supports **VR and AR natively**
-- ⚡ Loads **fast and runs smoothly**
-
-Whether you're showcasing your portfolio, creating client work, building an art installation, or just exploring creative possibilities—Needle Engine makes your 3D work accessible to the world.
-
-**The best part?** You don't need to be a programmer. You're a 3D artist, and that's exactly what Needle Engine needs.
-
----
-
 ## Next Steps
 
-Start your journey:
-
-1. **Install the Add-on** - [Download from needle.tools](https://needle.tools)
-2. **Watch a Quick Start Video** - [YouTube](https://www.youtube.com/@needle-tools)
-3. **Open a Sample Project** - See working examples in Blender
-4. **Join the Community** - [Discord](https://discord.needle.tools) for help and inspiration
-5. **Create Something Amazing** - Your first interactive 3D experience!
-
-:::tip Share Your Work!
-When you create something, share it in the Discord! The community loves seeing what artists create, and you'll get helpful feedback and encouragement.
-:::
-
----
-
-**Ready to bring your 3D art to life on the web? Let's go! 🚀**
-
-[Install Needle Engine →](https://needle.tools) • [Watch Video Tutorial →](https://www.youtube.com/@needle-tools) • [Join Discord →](https://discord.needle.tools)
+- [Get Started with Blender →](/docs/blender/) — install the add-on and create your first project
+- [Environment Lighting →](/docs/blender/environment) — custom HDRIs, skybox settings, and automatic compression
+- [Animation →](/docs/blender/animation) — playback, state machines, and timeline export
+- [Components →](/docs/blender/components) — 100+ built-in behaviors and creating your own
+- [Lightmapping →](/docs/blender/lightmapping) — baked lighting for stunning visuals with great performance
+- [Deploy Your Project →](/docs/how-to-guides/deployment/) — publish to Needle Cloud or self-host
+- [Sample Projects →](https://engine.needle.tools/samples) — interactive examples to learn from
+- [FAQ →](/docs/reference/faq) — common questions and troubleshooting
