neverisometric engine docs - an isometric js engine

Import

To import the engine simply use the link below:

<script src= "https://www.neverstudio.de/isometricEngine.js"></script>

You can of course also save the file locally:

<script src= "isometricEngine.js"></script>

If you intend to use the drawing functions pass your canvas Id first:
setCanvas("YourCanvasId")

Basic Scenes

The NeverIsometricEngine mainly consists of two classes and a collection of functions:
• The World object contains all physical objects.
It also manages the global physics and that everything is displayed.

• The IsoObject class can be used for creating physical objects.
It also defines the individuals objects physical behaviour, e.g. bounding boxes and the corresponding image.

The aspect ratio and the drawing functions

Before reading the list notice that there are two types of coordinates the NeverIsometricEngine works with:
• isometric coordinates: coordinates on the underlying isometric grid
• canvas coordinates: normal coordinates on the canvas

• setCanvas(id,pixelized=false,full=false,nWidth = undefined,nHeight = 500)
Sets the default canvas.
Set pixelized=true to enable position rounding in the draw function and a pixelated canvas.
Set full=true to make the canvas fullscreen.
There are nWidth and nHeight. You can only set one of them.
If you set nHeight to a specific value this will always be the local height of the canvas in Pixels.
So if the user resizes his screen to double the Height the canvas is stretched twice the amount of the original height. Resizing the screen horizontally will have no effect on the Canvas.
The same applies the other way around:
If you set nWidth, only horizontally resizing the screen will have an effect on the canvas and the local width of the Canvas will always stay the same.

TL;DR:

Set either nWidth or nHeight:
- If your content relies on the screens width e.g. a platformer you should set nWidth.
- If your content relies on the screen height you should set nHeight.
The standard drawing functions provided by the NeverIsometricEngine:

• setRatio(newRatio)
This function sets the aspect ratio of the underlying isometric grid.
The newRatio parameter is expected to be of type float.

• toScreen(isoX,isoY,isoZ=0)
A function that converts isometric coordinates to canvas coordinates.
Note that this might not align with the positions of the IsoObjects if the World object is centered on a specific object using World.center

• toIso(isoX,isoY,isoZ=0)
A function that converts canvas coordinates to coordinates on isometric coordinates.
Note that this might not align with the positions of the IsoObjects if the World object is centered on a specific object using World.center.

• grid(minimum = -1000,maximum = 1000, steps=10)
A function that displays the underlying isometric grid.
The minimum and the maximum parameters correspond to the minimum and maximum x and y values used in the grid.
The steps parameter changes the size of each square in the grid.

• isoLine(x1,y1,x2,y2,z1=0,z2=0,color="black",width = 5)
This function draws an isometric line on the canvas.
The x1,y1,z1 and the x2,y2,z2 parameters correspond to the positions of the start and end point.
The y values are the heights. If no value value is given it is assumed that they are of the value 0. The color parameter changes the color of the line.
The width parameter changes the linewidth.
The coordinates are expected to be isometric.

• drawImage(image,width,height,x,y,z=0,canvas = canvas, offset = [0,0])
Draws an image at the given coordinates on a screen.
The image parameter is expected to be a javascript image element.
The coordinates are expected to be isometric.
Please note that the coordinates are rounded before drawing if pixelized=true was passed to setCanvas.
The canvas parameter is the canvas to draw on.
The offset parameter is the x and y offset of the image in canvas coordinates.

The World Object

The world object is the central object of the NeverIsometricEngine, because it manages all other elements.

Properties passed during construction:
• canvas: Id of the Canvas Object all IsoObjects in the World Object are drawn on.
• keyObject: You can pass an Object here to make it possible to move it using the Arrow-Keys or WASD.

Displaying properties:
• displayBox: Whether the boundinhg boxes of the IsoObjects are displayed by default.
• displayShadow: Whether the shadow bounding boxes of the IsoObjects are displayed by default.
• displayImage: Whether the image of the IsoObjects are displayed by default.
These properties are added to the IsoObjects when they are added with the World.add() method.
• images: JSON containing all image paths from IsoObjects as keys and image objects as values.
Other properties:
• images: A JSON containing all images of the IsoObjects as image objects with the image paths as keys.
• mousePos: The position of the mouse as an isometric coordinate.
• objects: All objects that have been added to the world.

Methods of the World object:
• add(object,func= yourFunction)
This method can be used to add IsoObjects to the World object.
The first argument is the object you want to add.
The second optional parameter is a function that will be executed for each successfully loaded image Object associated with the added IsoObject.
It will log "loaded" together with the image path by default.

• loadImage(img,func= yourFunction)
This method can be used to load images and add them to the Worlds images JSON.
The img argument is the path of the image you want to load
The second optional func parameter is a function that will be executed when the image is loaded successfully.
It will log "loaded" together with the image path by default.

• remove(object)
This method removes objects already added to World.

• setKeyObject(object)
This method can be used to move an IsoObject already added to World with the Arrow keys or with WASD.
The only argument is the object you want to add.
There is a special mode for this function that can be enabled by setting World.smartMovement to true.
In this mode the moved object doesn't stop moving when colliding with a barrier but instead moves along the side of it.

• move(object,xchange,ychange,zchange=0)
This method can be used to move an IsoObject already added to World.
The first argument is the object you want to move.
The other arguments are the desired x,y and z changes.
Note that this function cuts each steps into smaller steps and checks whether the object collides for each smaller step.
The number of smaller steps can be manipulated by changing World.detail.
For example 0.1 corresponds to 10 smaller steps.

• center(object)
This method centers the canvas on a specific object.

• draw(clear=true)
Draws all IsoObjects that have been added onto the canvas.
If clear is set to false the canvas is not cleared before drawing.
WARNING: Everything that was drawn and that is not an IsoObject is deleted, if clear is set to true.

Iso Objects

Every Object that is supposed to be displayed by the world class has to be an IsoObject.
constructor(x,y,z,bounding,images,width=undefined,height=undefined,collision=undefined,screen=false)
Properties passed upon construction:
• x,y and z: These properties are isometric coordinates and they determine the position of the object.

• bounding: This property is an Array that sets the IsoObjects' collsion box. The Array has the following format: [[minimum_x,minimum_y,minimum_z],[maximum_x,maximum_y,maximum_z]]

• img: A list containing the paths to all images the IsoObject is supposed to use for drawing.

Optional:
• width: Width of the IsoObject (for drawing the image).

• height: Height of the IsoObject (for drawing the image).

• collision: A function that is executed when the IsoObject collides with another IsoObject.

• screen: You can also pass the x and y position as canvas coordinates. Then you have to set screen to true.

Other properties:
• aTurn and bTurn: 0 by default. They represent how the IsObject is turned.

• turnMap: A JSON that maps image paths to specific ways the IsoObject is turned.
Example:

{
		
 "front":{
		
  "angle":[0,0], // [aTurn,bTurn]
		
  "imgs":["img1.png","img2.png",...]
		
 },
		
 "behind":{
		
  "angle":[0,180], // [aTurn,bTurn]
		
  "imgs":["img5.png","img6.png",...]
		
 }
		
}

• displayBox, displayShadow, displayImage: Same like with world. Changes the standard setting.
Warning: If you want to modify these values do it after you added the IsoObject to world, because the World.add() method resets them to the World Objects defaults.

• activeImage: The url from the img list that is used for drawing.

• animationIndex: The index of the image that should be drawn in the "img" list of the current direction in turnMap.
E.g. with the above example turnMap, aTurn=0 and bTurn=0: animationIndex = 0 corresponds to "img1.png" as activeImage

• imgChange (in canvas coordinates): [0,0] by default. Changes the image position relative to the coordinate.
Since imgChange is overwritten by offsetMap in the update() method you should set the default value of offsetMap instead.

• offsetMap (in canvas coordinates): {"default":[0,0]} by default. JSON that maps image paths to corresponding offsets during drawing (like imgChange).
Example:

{
		
 "default":[0,0],// value that is used if the path of activeImage isn't a key of offsetMap
		
 "img1.png":[1,5],// offset that is used when drawing img1.png
		
 "img2.png":[1,5]// offset that is used when drawing img2.png
		
}

• hasCollision: Whether the IsoObject collides with other IsoObjects.

Methods:
• update(): This function updates some internal values for collision and drawing.
It also updates the activeImage depending on how the IsoObject is turned.

• move(xchange,ychange,zchange=0,draw=true): Moves the object. Collision is included. The canvas is only updated if draw is true.
The function returns true if the object didn't collide and false otherwise.

• moveForward(amount,draw=true): Moves the IsoObject forward based on how it is turned (currently only along the vertical plane). The canvas is only updated if draw is true.
The function returns true if the object didn't collide and false otherwise.

• moveTo(newx,newy,newz=0,draw=true): Moves the IsoObject to a specific position. The canvas is only updated if draw is true.
The function returns true if the object didn't collide and false otherwise.

• turn(aTurn,bTurn,draw=true): Turns the object by the given angles. The canvas is only updated if draw is true. Collision is included.

• turnTo(aTurn,bTurn,draw=true): Turns the object to the given angles. The canvas is only updated if draw is true.

• draw(image,offset=[0,0,0]): Used by the World Object to draw the IsoObject.

• animate(animation,min,max,steps=500): This method animates an object based on a JSON.
min and max are the start and end times of the animation in milliseconds. steps is the size of individual timesteps (only necessary if "all" is set in animation).
animation is a json that determines how the animation works. Here is an example:

{
		
 "all":{ // if the key is all the animation will be executed every steps milliseconds from min to max
		
  "move":[10,10,0], //move can be used for moving the object with collision. This example moves the object by 10 in x- and y-direction and 0 in z-direction. 
		
  "displayBox":true //you can also directly set most properties of IsoObject. The example is equivalent to displayBox = true.
		
 }
		
 "10": { // executed when 10 percent of the time between min and max have passed
		
  "moveForward":10, //moveForward can be used for moving the object with the moveForward method
		
  "add_animationIndex:1" //you can also add values to properties by writing "add_" at the beginning of their names. Lists will be added element by element. 
		
  "mult_animationIndex:2" //same as "add_" but with multiplication.
		
  "func_animationIndex:customFunc" //This is equivalent to animationIndex = customFunc(animationIndex)
		
 }
		
 
		
}

Note that image is not a path or url but an image object instead.
The array offset defines the x,y and z offset and is used by the World Object to center objects.

• collide(other): Returns true if the IsoObject and the other IsoObject other collide. Otherwise it returns false.

• layering(other): Used by the World Objects draw method. It determines whether the IsoObject is in front(1) or behind(1) the IsoObject other

• colliding(world=this.world): Returns a list containing all IsoObjects of world that collide with the IsoObject. If there are none it returns undefined
world is by default the world object the IsoObject is part of.

Examples

• A simple scene with a movable centered object:

<html>
<canvas id="canvas" width="1000px" height="1000px"></canvas>
<script src="https://www.neverstudio.de/isometricEngine.js"></script>
<script>
setRatio(1/4)
setCanvas("canvas")
var every = new World("canvas")
var centered = new IsoObject(100,100,0,[[-10,-10,0],[10,10,100]],["/image/of/centered/object.png"])
var other1 = new IsoObject(0,0,0,[[-10,-10,0],[10,10,100]],["image/of/other/object1.png"])
var other2 = new IsoObject(50,100,0,[[-10,-10,0],[10,10,100]],["image/of/other/object2.png"])
every.add(centered)
every.add(other1)
every.add(other2)
every.center(centered)
every.setKeyObject(centered)
</script>
</html>

• A simple game using the collision property of the IsoObject and other functionalities:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Isometric Game with Gameplay</title>
    <style>
        #score {
            font-size: 20px;
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
    <div id="score">Score: 0</div>
    <canvas id="gameCanvas" width="800" height="600"></canvas>

    <script src="isometricEngine.js"></script>
    <script>
        // Set the canvas ID and isometric ratio
        setCanvas("gameCanvas");
        setRatio(1 / 2);

        // Initialize variables
        var score = 0;
        var playerSpeed = 5;

        // Function to update the score
        function updateScore(newScore) {
            score = newScore;
            document.getElementById('score').innerText = 'Score: ' + score;
        }

        // Create the game world
        var gameWorld = new World("gameCanvas");

        // Create the player object
        var player = new IsoObject(100, 100, 0, [[-10, -10, 0], [10, 10, 50]], ["fig1.png"]);
		
		//create the collision function for the gems
		function gemCollision(gem,other){
			updateScore(score+1)//add points for finding the gem
			gem.moveTo(random(-200,200),random(-200,200))
		}
		
        // Create collectible items (e.g., gems)
        var gem1 = new IsoObject(200, 100, 0, [[-10, -10, 0], [10, 10, 70]], ["fig2.png"]);
        var gem2 = new IsoObject(300, 250, 0, [[-10, -10, 0], [10, 10, 70]], ["fig3.png"]);
        
        //Add collision function to gems
		gem1.collision = gemCollision
		gem2.collision = gemCollision
		
		
        // Create enemies that move back and forth
        var enemy1 = new IsoObject(400, 150, 0, [[-10, -10, 0], [10, 10, 70]], ["fig4.png"]);
        var enemy2 = new IsoObject(150, 300, 0, [[-10, -10, 0], [10, 10, 70]], ["fig4.png"]);
        
        //add collision function to enemies:
        //the game restarts when they collide with something
		enemy1.collision = resetGame
		enemy2.collision = resetGame
		
		
        // Add objects to the game world
        gameWorld.add(player);
        gameWorld.add(gem1);
        gameWorld.add(gem2);
        gameWorld.add(enemy1);
        gameWorld.add(enemy2);

        // Center the camera on the player and allow movement with the arrow keys
        gameWorld.center(player);
        gameWorld.setKeyObject(player);

        // Function to reset the game (called when player hits an enemy)
        function resetGame() {
			alert("restart")
            updateScore(0); // Reset score
            player.moveTo(100, 100, 0); // Move player back to the start
        }

        // Move the enemies back and forth
        function moveEnemies() {
            var direction = 1;
            setInterval(function() {
                // Make enemies move randomly
                gameWorld.move(enemy1, random(-20,20), random(-20,20), 0);
                gameWorld.move(enemy2, random(-20,20), random(-20,20), 0);
            }, 100);
        }
        
        
        // Game loop to continuously draw the scene and check for collisions
        function gameLoop() {
			//draw the world
            gameWorld.draw(true);
            
            requestAnimationFrame(gameLoop);
        }

        // Start the enemy movement and game loop
        moveEnemies();
        gameLoop();
    </script>
</body>
</html>

If you have any questions, you want to report any bugs or if you want to suggest changes to the engine don't hesitate to contact us.

Neverengine - documentation