Hello 3D Wiki

Documentation, tutorials, and guides to help you master Hello 3D

Hello Player

2026-02-07 21:53

Hello Player is the best experience for viewing Hello 3D scenes.

Hello 3D Player - Usage Guide

What is Hello 3D Player

Hello 3D Player is a standalone runtime for playing Hello 3D scenes without the full editor. It exports your scene as a minimal web application that can run in any browser or be deployed to a website.

Player Capabilities

Material Support

Hello Player supports all material types from the Hello 3D editor:

  • Standard - Basic physically-based material with metalness and roughness
  • Physical - Advanced material with transmission, clearcoat, iridescence, sheen, and more
  • Toon - Cartoon-style rendering with gradient maps
  • Glass - Transparent glass with refraction and transmission
  • Metal - High metalness material for metallic surfaces
  • Plastic - Low metalness material for plastic surfaces
  • Emissive - Self-illuminating material that glows
  • Wireframe - Shows object wireframe structure
  • Unlit - Basic material unaffected by lighting
  • MatCap - Material capture for stylized rendering
  • Depth - Renders based on depth values
  • Layered - Combines multiple material layers with blend modes

Texture Support

All texture maps are supported including:

  • Albedo/Diffuse maps
  • Normal maps
  • Roughness maps
  • Metalness maps
  • Emissive maps
  • Ambient Occlusion (AO) maps
  • Bump maps
  • Displacement maps
  • Alpha/Transparency maps
  • Clearcoat maps
  • Transmission maps
  • Iridescence maps
  • Sheen maps

Lighting Support

Complete lighting system identical to the editor:

  • Directional Light - Sun-like light from a direction
  • Point Light - Omnidirectional light from a point
  • Spot Light - Cone-shaped spotlight with angle and penumbra
  • Hemisphere Light - Sky and ground ambient lighting
  • Ambient Light - Global ambient illumination
  • Shadows - Configurable shadow types (Basic, PCF, PCF Soft, VSM)

Geometry Support

All primitive shapes and special geometry:

  • Cube, Sphere, Cylinder, Cone, Plane
  • Torus, Torus Knot, Capsule
  • Icosahedron, Dodecahedron, Octahedron, Tetrahedron
  • Circle, Ring, Tube, Lathe
  • Extrude, Polyhedron, Text 3D
  • Imported meshes (OBJ, FBX, GLTF, USDZ)
  • CSG operations (Constructive Solid Geometry)

Animation System

WebGPU-style animation system with:

  • Keyframe animation for position, rotation, scale
  • Multiple easing functions (linear, easeIn, easeOut, easeInOut, easeInBack, easeOutBack)
  • Loop and bounce options
  • Animation events (onLoad, onComplete)
  • Animation triggers via mouse, keyboard, scroll

Script Support

Full scripting runtime with all Script API features:

  • OnLoad, OnUpdate, OnClick handlers
  • Mouse events (enter, leave, down, up)
  • Scroll events
  • Math utilities and Vector3 support
  • Time and deltaTime
  • Helper functions (lookAt, distanceTo, moveLocal, etc.)

Camera Support

  • Perspective camera with FOV, near/far planes
  • Orthographic camera with zoom, left/right/top/bottom
  • Orbit controls for navigation

Environment and Background

  • HDRI environment maps
  • Color backgrounds
  • Environment lighting
  • Fog effects (color, near, far)

Post-Processing Effects

  • Bloom - Glow effect for bright areas
  • SMAA - Anti-aliasing
  • Tone Mapping - HDR color correction

Exporting to Hello Player

Step 1: Prepare Your Scene

Create and configure your scene in the Hello 3D editor:

  • Add objects and materials
  • Set up lighting
  • Create animations
  • Add scripts for interactivity

Step 2: Open Export Panel

Click the Export button in the toolbar or select File - Export to open the Export Panel.

Step 3: Select Hello Player Export

In the Export Panel, select "Hello 3D Player" as the export type.

Step 4: Export the ZIP

Click "Export Player ZIP" to download a complete player package.

ZIP Contents

The exported ZIP contains:

  • index.html - Main HTML file
  • scene/scene.json - Your scene data
  • package.json - Node.js dependencies
  • js/helloPlayer.jsx - Player runtime code
  • js/ScriptRuntime.js - Script execution engine
  • assets/ - Textures and materials
  • start.sh - Quick launcher (Mac/Linux)
  • README.md - Documentation
  • favicon.ico - Site icon

Running Hello Player

Quick Start (Mac/Linux)

./start.sh

This automatically installs dependencies and starts the dev server.

Manual Start

1. Extract the ZIP file

2. Install dependencies:

npm install

3. Start the dev server:

npm run dev

4. Open the URL shown (usually http://localhost:5173)

Build for Production

npm run build

Creates an optimized build in the dist folder.

Preview Production Build

npm run preview

Previews the production build locally.

Animation Events

Trigger animations with user interactions:

Mouse Events

  • mouseEnter - Animation starts when mouse enters object
  • mouseLeave - Animation starts when mouse leaves object
  • mouseDown - Animation starts on mouse button press
  • mouseUp - Animation starts on mouse button release

Scroll Events

  • scrollUp - Animation starts when scrolling up
  • scrollDown - Animation starts when scrolling down

Keyboard Events

  • keyDown - Animation starts when keys are pressed
  • keyUp - Animation starts when keys are released

Load Event

  • onLoad - Animation starts when scene loads

Deployment

Static Hosting

The player can be deployed to any static hosting service:

  • Netlify
  • Vercel
  • GitHub Pages
  • AWS S3
  • Any web server

Build and Deploy

npm run build

Upload the contents of the dist folder to your hosting service.

Limitations

What Does Not Work

  • Editor UI and editing features
  • Real-time material editing
  • Scene hierarchy manipulation
  • Importing new assets at runtime
  • 3D text fonts (requires pre-loaded fonts)

Preview Mode Only

Hello Player is designed for viewing and interacting with finished scenes. For editing, use the full Hello 3D editor.

Troubleshooting

Scene Does Not Load

  • Check that scene/scene.json exists
  • Verify the JSON is valid
  • Check browser console for errors

Textures Missing

  • Verify textures are in the assets folder
  • Check that texture paths are correct
  • Ensure textures are referenced in scene.json

Scripts Not Running

  • Scripts must be assigned to objects
  • Check browser console for script errors
  • Ensure script is enabled on the object

Animations Not Playing

  • Check animation settings (duration, loop)
  • Verify animation is triggered correctly
  • Check that objects have animation data