room3d v1.1.4

Room3D

Introduction

Room3D is a javascript plugin which you can use it to create a 3D room or box by html&css so easily.
It is light-weight and no need to rely on any other library. We design it just for help developers to quick create some simple 3D scene, or be used for some simple web 3D effects. If you need to create some huge complicated scene in your project, and hope it has a perfect render effect, you may not be content for it. We suggest to use some library which it based on WebGL like threeJs/babylonJs.

———— Author: DAN

中文文档    |    English Document   |   DEMO on gitee   |   DEMO on git   |   Github Repository   |   Npm Package

Get Started

1. After installed plugin you can get a constructor named Scene3D

   • Import plugin with script tag <script src="room3d.js"></script> , or
   • Install plugin by npm npm install room3d , then
     • use const Scene3D = require("room3d") or
     • import Scene3D from "room3d" to get Scene3D constructor.

2. Import stylesheet room3d.css

3. Create HTML element <div id="wraper"><div> , you can use id or class as the css selector. You can also set css rules width and height for the element. If you don't, the plugin will set the rules widt:100%; height:100%; for it.

4. Now you can write javascript codes to create 3D scene and 3D elements by configurations.

   let myScene = new Scene3D("#wraper",{
     width:"400px",
     depth:"400px",
     rooms:[
       {
         height:"400px",
         boxes:[
           {
             width:"100px",
             depth:"100px",
             height:"100px",
             left:"150px",
             top:"160px",
             color:"green"
           }
         ]
       }
     ]
   })

Relation Diagram

API

Scene Object

Options

Methods

Create a Scene object let Scene = new Scene3D("#Scene1",{options...}) , it can use the methods below:

• Scene.showGrid( boolean )

  • Parameters\ boolean {boolean} | Required | True means visible, false means hidden

  • Returns\ Return this current Scene object, which be use for chain calling.

  • Details\ To show or hide the grid of scene.

• Scene.resetScene()

  • Parameters\ -

  • Returns\ Return this current Scene object, which be use for chain calling.

  • Details\ Reset the scene rotation and scale to initial status.

• Scene.buildRoom( options )

  • Parameters\ options {object} | Optional | Options object, refer to Room configurate options

  • Returns\ Return the new Room object

  • Details\ Use the options that passed in to create room manually. If it's empty, will use the default options.

Room Object

Options

The options top right bottom left are use for locate Room's horizontal position relative to the Scene, you just need to set only one of left and right . And the same as top and bottom .\ For the definitions of width, depth and height, you can see the diagram at the top of this document.

Methods

Create and get a Room object by let Room = Scene.buildRoom() . If you want to get a existing Room, you can get it by let Room = Scene.rooms[index] . It can use the methods below:

• Room.showFloor( boolean )
• Room.showWall( boolean )

• Room.showLine( boolean )

  • Parameters\ boolean {boolean} | Required | True means visible, false means hidden

  • Returns\ Return this Room object that be use for chain calling

  • Details\ Be use for show or hide Floor, Walls and Corner Lines.

• Room.backface( value )

  • Parameters\ value {string} | Required | The optional values are "hidden" and "visible" .

  • Returns\ Return this Room object that be use for chain calling.

  • Details\ Be use for set the value of css rule backface-visibility of Wall elements. Specifically, If set "hidden", the side which facing the screen of wall will become transparent. So that the elements in the Room can be seen, and it does not block the mouse events on this elements in the Room.

• Room.buildDoor( wall , doorOptions )

  • Parameters\ wall {string} | Required | The optional values are: "left" , "right" , "fore" and "back" doorOptions {object} | Optional | Door object configurations, refer to the configurations below.

  • Returns\ Return the new Door object

  • Details\ Use the options that passed in to create a Door manually

    Door Options

    Name	Type	Default	Description
    className	string	""	That will be use for Door dom element's class name after concatenated with "Room3D_door_"
    width	string	"60px"	The value must contain unit, Percentages are supported
    height	string	"120px"	The value must contain unit, Percentages are supported
    left	string	"50%"	Distance from Door to the left edge of Wall, the value must contain unit. Percentages are supported.
    right	string	-	Distance from Door to the right edge of Wall, the value must contain unit. Percentages are supported. Notice that if you want to position the Door with right option, you must set "auto" for the left option
    show	boolean	true	Show Doors, If set to false , you will only see a rectangular hole in the wall.
    type	string	"single left"	Type of Door. Optional values are: "single left" single Door with left shaft, "single right" single Door with right shaft, "double" double Doors.
    openSide	string	"outside"	Direction of Door opening. Optional values are: "outside" and "inside"
    color	string	"#634A42"	Color of Door.
    doorFrameWidth	string	"3px"	The width of Door frame, the value must contain unit, Percentages are NOT supported.
    doorFrameColor	string	"#3B2A24"	Color of Door frame

    Door Methods

    Use let Door = Room.buildDoor( wall , doorArray )[index] or let Door = Room.walls[wall].doors[index] to get Door object, it can use the methods below:

    • Door.openDoor() Open the door
    • Door.closeDoor() Close the door

• Room.buildBox( options )

  • Parameters\ options {object} | Optional | Options object, refer to Box configurate options

  • Returns\ Return the new Box object

  • Details\ Use the options that passed in to create Box manually. If it's empty, will use the default options.

• Room.destroy()

  • Parameters\ -

  • Returns\ -

  • Details\ Destroy Room object

Box Object

Options

The options top right bottom left are use for locate Box's horizontal position relative to the corresponding Room, you just need to set only one of left and right . And the same as top and bottom .

Methods

Create a Marker object by let Box = Room.buildBox() then get it. If you want to get a existing Marker, you can get it by let Box = Room.boxes[index] . It can use the methods below:

• Box.showLine( boolean )

• Box.showMarker( boolean )

  • Parameters\ boolean {boolean} | Required | Pass in true to show, and false to hide

  • Returns\ Return this Box object, which be use for chain calling

  • Details\ Be use for show or hide the border line and Marker.

• Box.buildMarker( options )

  • Parameters\ options {object} | Optional | Marker configurations

  • Returns\ Return the new Marker

  • Details\ There is a correspooding Marker object is create automatically at each Box object created. So the method updateMarker() actually destroys the original Marker first, and then creates a new Marker with the new configurations. If you just want to update content of Marker, you can use the method updateMarker() of Marker object.

• Box.destroy()

  • Parameters\ -

  • Returns\ -

  • Details\ Destroy Box object

Marker Object

Options

Since in DOM structure the Marker elements are created directly in scene element, so their top right bottom left are positioned relative to the scene element. You just set only one between left and right . And the same as top and bottom. And since the default value of left and top is an expression that makes the Marker be created right above the box. So if you want to use right and bottom for positioning, you must set the corresponding left and top values to auto .

Methods

Create and get a Marker object by let Marker = Box.buildMarker() . If you want to get a existing Marker, you can get it by let Marker = Box.marker . It can use the methods below:

• Marker.updateMarker( params )

  • Parameters\ params {object} | Required | The params object must contain properties that match the Marker content template and the values that need to be updated.

  • Returns\ Return this Marker object

  • Details\ Be use for update Marker content template.

• Marker.destroy()

  • Parameters\ -

  • Returns\ -

  • Details\ Destroy Marker object

Notice

1. All the options of length and distance must set the same unit, "px" is recommended. Otherwise there will be some bugs due to the unit conversion.

2. If two immediately adjacent rooms that need to create doors on adjacent walls, you need to use buildDoor() method for the corresponding wall objects of both rooms on the symmetrical positions while set one of the doors invisable, then you can achieve it.

3. You can also add css rule background-image for various elements in the scene, simulate mapping effect to achieve richer scene

NPM Package Versions & Updates

• 1.0.0 Release date: 2022/6/8
  • 1.0.1 & 1.0.2 Release date：2022/6/8
    • Modify readme.md
  • 1.1.0 Release date: 2022/6/15
    • Marker object add property scene , its value points to the current Scene objec.
    • Box object add method .destroy()
    • Room object add method .destroy()

Others