Three-tools by BACE

This project iterates on the previous three-devtools project by @jsantell. Credits to Webextension Browser-Polyfill by @rafaelsc for making this extension Chrome-compatible.

Basic Setup
Referencing three-devtools
Documentation
Changes from three-devtools
Next Steps
Troubleshooting
To Contribute

Basic Setup as Chrome Extension

clone this repository
run commands: npm ci and npm run build:dist:chrome
open Chrome Extensions -> Manage Extensions
Change settings into Developer Mode
Load unpacked this repository
After making changes, run npm run build:dist:chrome again and click Update in the Manage Extensions page
Happy debugging :)

Referencing three-devtools

Three-tools follows the same project architecture and file structure as three-devtools. Please take a look at the three-devtools DEVELOPMENT.md for details.

Architecture

The architecture follows the same structure as three-devtools'. Take a look at the tech stack below for descriptions on different technologies we've used:

Backend Tech Stack

JavaScript
Webextension Browser-Polyfill to make custom-elements Chrome-compatible
Chrome API to create DevTools panel and enable message passing

Frontend Tech Stack

JavaScript/HTML/CSS
LitElement to create custom HTML elements
three.js
egjs to check if a computer is in light or dark mode

Commands

The following are the most relevant commands among those scripted by three-devtools

npm run build:deps builds dependencies via @pika/web
npm run build:dist:chrome builds a zip file of the extension in the dist directory for Chrome browsers.

Documentation

Getting started with Three-tools

The Three-tools UI is full of information but might be a bit overwhelming! Relevant information is separated into different panels for your convenience. Recommended starting points for learning how Three-tools can improve your productivity: (Within each panel, numbers and values can be typed or dragged to change)

Scenes & Cameras panel

View and change scene and camera properties Click the dropdown menu of scenes and cameras to view different entity maps. Scenes and 3D objects are currently editable but camera properties are not able to be altered.

Select entities from the tree to view a smaller panel to the right with their properties
Use the search bar to search for entities by Name, Type or UUID (Note: UUID is not persistent and may change on reload)
Use the refresh button to reload the panel
Use the visibility icons to toggle entities on and off
For Scenes and 3D Objects / Entities:
- Developers can view the Type, UUID, and Name properties
- Developers can see the Transform and Rendering information and adjust those properties
- Within the Transform tab:
  - Adjust the position, rotation and scale
  - Use the Matrix Auto Update toggle to adjust whether or not changes are immediately reflected in the DOM
  - Click the Save button to save specific properties if you would like to go back to them
  - Click the Display Saved Data to open a popup of the saved specs as well as log those specs to your console
- Within the Rendering tab:
  - Adjust the Render Order
  - The visibility toggle here works the same way as the visibility icon
  - Adjust shadow properties
- FOR ONLY SCENES:
  - A Background tab will be available to adjust the Background color if it has been set (currently no support for Background textures or the default null background)
For Cameras:
- View the Type, UUID, Name and type specific properties
- These properties are not currently adjustable

Geometries panel

View and change geometry properties Lists the Geometries / BufferGeometries rendered to the scene(s) available

Use the search bar to search for entities by Name or UUID (Note: UUID is not persistent and may change on reload)
Use the refresh button to reload the panel
Use the visibility icons to toggle the entities on and off
Select geometries from the list to see a list of their properties rendered on the right
- Type, UUID and Name
- Index
- Groups
  - If Groups is an array, it will be hyperlinked to open more information in a new tab
- Morph Targets Relative

Materials panel

View and change materials properties Lists the Materials rendered to the scene(s) available

Use the search bar to search for entities by Name or UUID (Note: UUID is not persistent and may change on reload)
Use the refresh button to reload the panel
Use the visibility icons to toggle the entities on and off
Select Materials from the list to see a list of their properties
- Type, UUID, Name
- Color: adjustable by color map
- Materials Type Specific Properties
  - if null, not editable
  - otherwise, can be adjusted
- Other nested tabs for more type specific properties

Textures panel

View and change textures properties Lists the Textures rendered to the scene(s) available

Use the search bar to search for entities by Name or UUID (Note: UUID is not persistent and may change on reload)
Use the refresh button to reload the panel
Use the visibility icons to toggle the entities on and off
Select Textures from the list to see a list of their properties
- Changes to these properties are not fully supported
- Tabs:
  - Filters
    - Min Filter -- dropdown menu of options
    - Mag Filter -- dropdown menu of options
  - Wrapping
    - Wrap S -- dropdown menu of options
    - Wrap T -- dropdown menu of options
  - Transform
    - Offset
    - Repeat
    - Rotation
    - Center
    - matrixAutoUpdate
    - Matrix

Renderer panel

View rendering info from the scenes available. Note: this information is not always correct due to the renderer.info not being properly reset. If the information looks incorrect, please see the three.js renderer.info documentation for further information about manually resetting your renderer.info

Left panel:
- Renderer tab tracks different data with a setInterval function to update every second. This tab lists the information from WebGLRenderer.info.render
  - frames
  - draw calls
  - triangles
  - points
  - lines
- Memory tab tracks data from WebGLRenderer.info.memory
  - geometries
  - textures
  - programs
Right panel: WebGLRenderer
- Lists the type of renderer used, name and properties
- (gammaFactor has been removed from THREE.WebGLRenderer so we removed that property)
- Tone Mapping
- Shadow Map
- Buffer Clearing
- Capabilities
- Clipping
- Scene
- Morph Limits

Changes from three-devtools

removed requirement to hit reload button when extension is first opened
implemented search bar functionality to allow users to search through entities by uuid, name or type
added hide/show toggle icon to control visibility of scene elements, textures, geometries and materials
updated three.js version to the latest version
updated UI/UX for easy debugging experience
support for rendering camera information for debugging
- changing camera properties currently does not work
- this functionality creates an array of DevToolsScenes corresponding to the cameras as well as TransformControls objects for each DevToolsScene
- these objects (DevToolsScenes and TransformControls) are not yet functional
- currently calls updateMatrixWorld but does not see properties updated
- updated dropdown menu on scene viewing tab to include Camera entities
support for scene background colors
added ability to save transformed properties
- information is then opened in a popup window and logged in the console

Recommended Next Steps:

Add support to change camera properties (Recommended to take a look at TransformControls.js)
Once the camera works, add functionality to 'highlight' the selected scene
Update Manifest version to version 3 (version 2 will be deprecated in ~1 year)
- Update Manifest.json to accept inject.js file as a web resource
- Activate background.js as a usable service worker
Ensure support for all Materials properties
Make the panels resizeable
Create a persistent unique identifier (UUID is not persistent currently)
Renderer info is not always correct -- please see renderer.info in the three.js docs (hyperlinked in the renderer info tab of the devtool)

Troubleshooting:

You have an error that you cannot describe or it is your first error
- Reload the page the extension, this will solve most problems
You cannot access three-tools in your chrome extension panel
- Exit out of chrome devtools inspector and re-enter
You only see "three-tools requires a page reload"
- Go to a page utilizing three.js otherwise three-tools will not load
- three-tools will not recognize three.js objects inside iframes
You are on three.js website and it still will not load or does not render objects
- Chrome extension still does not have any compatabilities with websites using i-frames, if you would like to use our tool remove any iframes for our product to register your code.
You cannot type h into the searchbar
- Chrome extension has a bug where h cannot be typed into our extensions searchbar, use shift h in this case
You are having an issue with the build-dist.sh file
- Check this stack overflow
  - Recommended to try sed -i -e 's/\r$//' build-dist.sh and ./build-dist.sh

To Contribute:

Fork this repository
Create a new branch with the name of the feature to add / change
Create a PR to the dev branch
Use descriptive commit messages and include comments in the description of your PR
When completed with your feature please send an email to bacetools@gmail.com, and one of the members will review and merge

oslabs-beta/BACE