CopperLicht API Documentation
Class CL3D.CopperLicht
The main class of the CopperLicht engine, representing the 3D engine itself.
Class Overview
CL3D.CopperLicht(elementIdOfCanvas, showInfoTexts, fps, showFPSCounter, loadingScreenText, noWebGLText, fullpage, pointerLockForFPSCameras, loadingScreenBackgroundColor)
The main class of the CopperLicht 3D engine.
You can create an instance of this class using for example startCopperLichtFromFile, but using
code like this will work of course as well:
var engine = new CL3D.CopperLicht('yourCanvasID'); engine.load('somefile.ccbz');
- Parameters:
- elementIdOfCanvas
- id of the canvas element embedded in the html, used to draw 3d graphics.
- showInfoTexts
- if set to true, this shows loading indicators and error texts. If set to false no text is shown and you have to do this yourself.
- fps
- {Number} frames per second to draw. Uses a default of 60 if set to null.
- showFPSCounter
- {Boolean} set to true to show a frames per second counter
- loadingScreenText
- {String} optional parameter specifying a loadingScreen text. Setting this to a text like "Loading" will cause a loading screen with this text to appear while the file is being loaded.
- noWebGLText
- {String} optional parameter specifying a text to show when there is no webgl.
- fullpage
- {Boolean} optional parameter, set to true to expand canvas automatically to the full browser size.
- pointerLockForFPSCameras
- {Boolean} optional parameter, set to true to automatically use pointer lock for FPS cameras
- loadingScreenBackgroundColor
Field Attributes | Field Name and Description |
---|---|
Event handler called after the scene has been completely drawn.
|
|
Event handler called before animating the scene.
|
|
Event handler called before the scene will be completely drawn.
|
|
Event handler called after the scene description file has been loaded sucessfully (see CopperLicht.load().
|
|
Event handler called before sending a received "mouse down" event to the scene graph.
|
|
Event handler called before sending a received "mouse up" event to the scene graph.
|
Method Attributes | Method Name and Description |
---|---|
addScene(scene)
Adds a new CL3D.Scene
|
|
Draws and animates the 3d scene.
|
|
get2DPositionFrom3DPosition(pos3d)
Returns the 2D pixel position on the screen from a 3D position.
|
|
Returns a 3D point from a 2D pixel coordinate on the screen.
|
|
Returns the last X coordinate where the mouse was pressed over the canvas.
|
|
Returns the last Y coordinate where the mouse was pressed over the canvas.
|
|
Returns the last X movement coordinate when in pointer lock mode
|
|
Returns the last Y movement coordinate when in pointer lock mode
|
|
Returns the last X coordinate in pixels of the cursor over the canvas, relative to the canvas.
|
|
Returns the last Y coordinate in pixels of the cursor over the canvas, relative to the canvas.
|
|
return a reference to the currently used Renderer.
|
|
getScene()
return a reference to the currently active Scene.
|
|
Returns all available scenes.
|
|
Returns the TextureManager used to load textures.
|
|
gotoScene(scene)
Switches the current scene to a new CL3D.Scene.
|
|
gotoSceneByName(scene, ignorecase)
Switches the current scene to a new CL3D.Scene by scene name.
|
|
handleKeyDown(evt)
When CopperLicht is created, it will register the document.onkeydown event with this function.
|
|
handleKeyUp(evt)
When CopperLicht is created, it will register the document.onkeyup event with this function.
|
|
handleMouseDown(evt)
When CopperLicht is created, it will register the onmousedown event of the canvas with this function.
|
|
handleMouseMove(evt)
When CopperLicht is created, it will register the onmousemove event of the canvas with this function.
|
|
handleMouseUp(evt)
When CopperLicht is created, it will register the onmouseup event of the canvas with this function.
|
|
handleMouseWheel(evt)
|
|
Initializes the renderer, you need to call this if you create the engine yourself without
using one of the startup functions like startCopperLichtFromFile.
|
|
Returns true if the current document has the mouse pointer locked or not.
|
|
Returns true of CopperLicht is currently loading a scene file
|
|
Returns if the mouse is currently pressed over the canvas.
|
|
Returns if the mouse is overt the canvas at all
|
|
load(filetoload, importIntoExistingDocument, functionToCallWhenLoaded)
Loads a the scene from a CopperCube file and displays it.
|
|
reloadScene(scene)
Reloads a scene, triggered only by the CopperCube Action 'RestartScene'
|
|
sendMouseWheelEvent(delta)
|
|
switchToFullscreen(withPointerLock, elementToSetToFullsceen)
Switches to fullscreen and locks the pointer if wanted.
|
Field Detail
OnAfterDrawAll
Event handler called after the scene has been completely drawn. You can use this to draw some additional stuff like
2d overlays or similar. Use it for example like here:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnAfterDrawAll = function() { var renderer = engine.getRenderer(); if (renderer) { // TODO: draw something additionally here } };
OnAnimate
Event handler called before animating the scene. You can use this to manipulate the 3d scene every frame.
An example how to use it looks like this:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnAnimate = function() { var scene = engine.getScene(); if (scene) { // TODO: do your game logic here } };
OnBeforeDrawAll
Event handler called before the scene will be completely drawn. You can use this to draw some additional stuff like
weapons or similar. Use it for example like here:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnBeforeDrawAll = function() { var renderer = engine.getRenderer(); if (renderer) { // TODO: draw something here } };
OnLoadingComplete
Event handler called after the scene description file has been loaded sucessfully (see CopperLicht.load().
Can be used to hide a loading screen after loading of the file has been finished. Use it for example like here:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnLoadingComplete = function() { // Do something here };
OnMouseDown
Event handler called before sending a received "mouse down" event to the scene graph. You can use this to intercept
mouse events in your game. Return 'true' if you handled the event yourself and don't want the 3D scene to reveive this
event. An example how to use it looks like this:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnMouseDown = function() { var scene = engine.getScene(); if (scene) { // TODO: do your game logic here // return true; // <- return true here if you handled the event yourself } return false; // let the engine handle this click };
OnMouseUp
Event handler called before sending a received "mouse up" event to the scene graph. You can use this to intercept
mouse events in your game. Return 'true' if you handled the event yourself and don't want the 3D scene to reveive this
event. An example how to use it looks like this:
var engine = startCopperLichtFromFile('3darea', 'test.ccbz'); engine.OnMouseUp = function() { var scene = engine.getScene(); if (scene) { // TODO: do your game logic here // return true; // <- return true here if you handled the event yourself } return false; // let the engine handle this click };
Method Detail
addScene(scene)
Adds a new CL3D.Scene
- Parameters:
- scene
draw3dScene()
Draws and animates the 3d scene.
To be called if you are using your own rendering loop, usually this has not to be called at all.
This will also call OnAnimate() before starting to draw anything, and call OnAfterDrawAll() after everything
has been drawn.
{CL3D.Vect2d}
get2DPositionFrom3DPosition(pos3d)
Returns the 2D pixel position on the screen from a 3D position. Uses the current projection and view matrices stored in the renderer,
so the 3d scene should have been rendered at least once before to return a correct result.
- Parameters:
- {CL3D.Vect3d} pos3d
- 3d position as Vect3d.
- Returns:
- {CL3D.Vect2d} returns a 2d position as Vect2d if a 2d pixel position can be found, and null if not (if the pixel would be behind the screen, for example).
{CL3D.Vect3d}
get3DPositionFrom2DPosition(x, y)
Returns a 3D point from a 2D pixel coordinate on the screen. Note: A 2D position on the screen does not represent one
single 3D point, but a actually a 3d line. So in order to get this line, use the 3d point returned by this function and the position
of the current camera to form this line.
- Parameters:
- x
- {Number} x coordinate on the canvas. You can use CopperLicht.getMouseX for the current mouse cursor position.
- y
- {Number} y coordinate on the canvas. You can use CopperLicht.getMouseY for the current mouse cursor position.
- Returns:
- {CL3D.Vect3d} returns a 3d vector as described above, or null if not possible to do this calculation (for example if the browser does not support WebGL).
getMouseDownX()
Returns the last X coordinate where the mouse was pressed over the canvas.
see also CopperLicht.OnMouseDown and CopperLicht.OnMouseUp.
getMouseDownY()
Returns the last Y coordinate where the mouse was pressed over the canvas.
see also CopperLicht.OnMouseDown and CopperLicht.OnMouseUp.
getMouseMoveX()
Returns the last X movement coordinate when in pointer lock mode
getMouseMoveY()
Returns the last Y movement coordinate when in pointer lock mode
getMouseX()
Returns the last X coordinate in pixels of the cursor over the canvas, relative to the canvas.
see also CopperLicht.OnMouseDown and CopperLicht.OnMouseUp.
getMouseY()
Returns the last Y coordinate in pixels of the cursor over the canvas, relative to the canvas.
see also CopperLicht.OnMouseDown and CopperLicht.OnMouseUp.
getRenderer()
return a reference to the currently used Renderer.
getScene()
return a reference to the currently active Scene.
getScenes()
Returns all available scenes.
Returns an array containing all Scenes.
{CL3D.TextureManager}
getTextureManager()
Returns the TextureManager used to load textures.
- Returns:
- {CL3D.TextureManager} returns the reference to the used texture manager.
gotoScene(scene)
Switches the current scene to a new CL3D.Scene.
- Parameters:
- {CL3D.Scene} scene
- The new CL3D.Scene to be activated.
gotoSceneByName(scene, ignorecase)
Switches the current scene to a new CL3D.Scene by scene name.
- Parameters:
- scene
- {String} The name of the new CL3D.Scene to be activated.
- ignorecase
- {Boolean} set to true to ignore the case of the name
handleKeyDown(evt)
When CopperLicht is created, it will register the document.onkeydown event with this function.
If you need to handle it yourself, you should call this function with the event parameter so
that all animators still work correctly.
- Parameters:
- evt
handleKeyUp(evt)
When CopperLicht is created, it will register the document.onkeyup event with this function.
If you need to handle it yourself, you should call this function with the event parameter so
that all animators still work correctly.
- Parameters:
- evt
handleMouseDown(evt)
When CopperLicht is created, it will register the onmousedown event of the canvas with this function.
If you need to handle it yourself, you should call this function with the event parameter so
that all animators still work correctly.
- Parameters:
- evt
handleMouseMove(evt)
When CopperLicht is created, it will register the onmousemove event of the canvas with this function.
If you need to handle it yourself, you should call this function with the event parameter so
that all animators still work correctly.
- Parameters:
- evt
handleMouseUp(evt)
When CopperLicht is created, it will register the onmouseup event of the canvas with this function.
If you need to handle it yourself, you should call this function with the event parameter so
that all animators still work correctly.
- Parameters:
- evt
handleMouseWheel(evt)
- Parameters:
- evt
initRenderer()
Initializes the renderer, you need to call this if you create the engine yourself without
using one of the startup functions like startCopperLichtFromFile.
- Returns:
- returns true if successful and false if not (if the browser does not support webgl, for example).
isInPointerLockMode()
Returns true if the current document has the mouse pointer locked or not. Useful for first person shooters
isLoading()
Returns true of CopperLicht is currently loading a scene file
isMouseDown()
Returns if the mouse is currently pressed over the canvas.
isMouseOverCanvas()
Returns if the mouse is overt the canvas at all
load(filetoload, importIntoExistingDocument, functionToCallWhenLoaded)
Loads a the scene from a CopperCube file and displays it.
This will also initialize the renderer if this has not been done before. You can also use the event handler CopperLicht.OnLoadingComplete to
check if the loading of the file has completed.
- Parameters:
- filetoload
- a filename such as 'test.ccbjs' or 'test.ccbz' which will be loaded, displayed and animated by the 3d engine. .ccbjs and .ccbz files can be created using the CopperCube editor, it is free to use for 21 days.
- importIntoExistingDocument
- if set to true, this will load all scenes into the existing document. It won't replace the current loaded data with the data from that file, but append it. This means that the scenes in the .ccbjs or .ccbz file will be added to the list of existing scenes, instead of replacing them.
- functionToCallWhenLoaded
- (optional) a function to call when the file has been loaded
reloadScene(scene)
Reloads a scene, triggered only by the CopperCube Action 'RestartScene'
- Parameters:
- {CL3D.Scene} scene
- The new CL3D.Scene to be reloaded.
sendMouseWheelEvent(delta)
- Parameters:
- delta
switchToFullscreen(withPointerLock, elementToSetToFullsceen)
Switches to fullscreen and locks the pointer if wanted. Note: This function must be called in reaction of a user interaction,
otherwise the browser will ignore this. The best is to call it from the event handler of for example an onClick even of a button.
- Parameters:
- withPointerLock
- If set to 'true', the mouse pointer will be locked, otherwise the app only switches to full screen.
- elementToSetToFullsceen
- the element which should be fullscreen. Set this to null to make the canvas fullscreen. But you can also set it to - for example - the parent of the canvas for showing some more info.