Crafty.viewport

Events

ViewportScroll: when the viewport's x or y coordinates change

ViewportScale: when the viewport's scale changes

ViewportResize: when the viewport's dimension's change

InvalidateViewport: when the viewport changes

StopCamera: when any camera animations should stop, such as at the start of a new animation.

CameraAnimationDone: when a camera animation reaches completion

Viewport is essentially a 2D camera looking at the stage. Can be moved or zoomed, which in turn will react just like a camera moving in that direction.

There are multiple camera animation methods available - these are the viewport methods with an animation time parameter and the follow method. Only one animation can run at a time. Starting a new animation will cancel the previous one and the appropriate events will be fired.

Tip: At any given moment, the stuff that you can see is...

x between (-Crafty.viewport._x) and (-Crafty.viewport._x + (Crafty.viewport._width / Crafty.viewport._scale))

y between (-Crafty.viewport._y) and (-Crafty.viewport._y + (Crafty.viewport._height / Crafty.viewport._scale))

Example

Prevent viewport from adjusting itself when outside the game world. Scale the viewport so that entities appear twice as large. Then center the viewport on an entity over the duration of 3 seconds. After that animation finishes, start following the entity.

var ent = Crafty.e('2D, DOM').attr({x: 250, y: 250, w: 100, h: 100});

Crafty.viewport.clampToEntities = false;
Crafty.viewport.scale(2);
Crafty.one("CameraAnimationDone", function() {
    Crafty.viewport.follow(ent, 0, 0);
});
Crafty.viewport.centerOn(ent, 3000);

Methods

.centerOn()
.mouselook()
.follow()
.onScreen()
.pan()
.rect()
.scale()
.scroll()
.zoom()

Back to top

Crafty.viewport._scale

src/graphics/viewport.js#L87-L98

This value is the current scale (zoom) of the viewport. When the value is bigger than 1, everything looks bigger (zoomed in). When the value is less than 1, everything looks smaller (zoomed out). This does not alter the size of the stage itself, just the magnification of what it shows.

This is a read-only property: Do not set it directly. Instead, use Crafty.viewport.scale(...) or Crafty.viewport.zoom(...)

Back to top

Crafty.viewport.bounds

src/graphics/viewport.js#L102-L124

A rectangle which defines the bounds of the viewport. It should be an object with two properties, max and min, which are each an object with x and y properties.

If this property is null, Crafty uses the bounding box of all the items on the stage. This is the initial value. (To prevent this behavior, set Crafty.viewport.clampToEntities to false)

If you wish to bound the viewport along one axis but not the other, you can use -Infinity and +Infinity as bounds.

Example

Set the bounds to a 500 by 500 square:

Crafty.viewport.bounds = {min:{x:0, y:0}, max:{x:500, y:500}};

Back to top

Crafty.viewport.clampToEntities

src/graphics/viewport.js#L47-L56

Decides if the viewport functions should clamp to game entities. When set to true functions such as Crafty.viewport.mouselook() will not allow you to move the viewport over areas of the game that has no entities. For development it can be useful to set this to false.

Back to top

Crafty.viewport.y

src/graphics/viewport.js#L73-L84

Will move the stage and therefore every visible entity along the y axis in the opposite direction.

When this value is set, it will shift the entire stage. This means that entity positions are not exactly where they are on screen. To get the exact position, simply add Crafty.viewport.y onto the entities y position.

Back to top

Crafty.viewport.centerOn()

src/graphics/viewport.js#L307-L323

public void Crafty.viewport.centerOn(Object target, Number time)

Object target: An entity with the 2D component

Number time: The duration in ms of the camera motion

Centers the viewport on the given entity.

Example

var ent = Crafty.e('2D, DOM').attr({x: 250, y: 250, w: 100, h: 100});
Crafty.viewport.centerOn(ent, 3000);

Back to top

Crafty.viewport.mouselook()

src/graphics/viewport.js#L468-L481

public void Crafty.viewport.mouselook(Boolean active)

Boolean active: Activate or deactivate mouselook

Toggle mouselook on the current viewport. Simply call this function and the user will be able to drag the viewport around.

If the user starts a drag, "StopCamera" will be triggered, which will cancel any existing camera animations.

Back to top

Crafty.viewport.x

src/graphics/viewport.js#L60-L71

Will move the stage and therefore every visible entity along the x axis in the opposite direction.

When this value is set, it will shift the entire stage. This means that entity positions are not exactly where they are on screen. To get the exact position, simply add Crafty.viewport.x onto the entities x position.

Back to top

Crafty.viewport.follow()

src/graphics/viewport.js#L252-L270

public void Crafty.viewport.follow(Object target, Number offsetx, Number offsety)

Object target: An entity with the 2D component

Number offsetx: Follow target's center should be offsetx pixels away from viewport's center. Positive values puts target to the right of the screen.

Number offsety: Follow target's center should be offsety pixels away from viewport's center. Positive values puts target to the bottom of the screen.

Follows a given entity with the 2D component. If following target will take a portion of the viewport out of bounds of the world, following will stop until the target moves away.

Example

var ent = Crafty.e('2D, DOM').attr({w: 100, h: 100});
Crafty.viewport.follow(ent, 0, 0);

Back to top

Crafty.viewport.onScreen()

src/graphics/viewport.js#L837-L846

public Crafty.viewport.onScreen(Object rect)

rect: A rectangle with field {_x: x_val, _y: y_val, _w: w_val, _h: h_val}

Test if a rectangle is completely in viewport

Back to top

Crafty.viewport.pan()

src/graphics/viewport.js#L188-L207

public void Crafty.viewport.pan(Number dx, Number dy, Number time[, String|function easingFn])

Number dx: The distance along the x axis

Number dy: The distance along the y axis

Number time: The duration in ms for the entire camera movement

easingFn: A string or custom function specifying an easing. (Defaults to linear behavior.) See Crafty.easing for more information.

Pans the camera a given number of pixels over the specified time

Example

// pan the camera 100 px right and down over the duration of 2 seconds using linear easing behaviour
Crafty.viewport.pan(100, 100, 2000);

Back to top

Crafty.viewport.rect()

src/graphics/viewport.js#L154-L178

public Object Crafty.viewport.rect([Object out])

Object out: an optional Object to write the rect to

[Returns]: a rectangle encompassing the currently visible viewport region. Contains the _x,_y,_w,_h properties.

Convenience method which returns a rect of the currently visible viewport region. With no supplied out parameter, this method returns an internally reused object across invocations. If you want to save the viewport region for later use, pass an out argument instead, where the region will be written to.

Example

The rect is equivalent to the following properties:

var rect = Crafty.viewport.rect();

rect._x === -Crafty.viewport._x
rect._y === -Crafty.viewport._y
rect._w === Crafty.viewport._width / Crafty.viewport._scale
rect._h === Crafty.viewport._height / Crafty.viewport._scale

Back to top

Crafty.viewport.scale()

src/graphics/viewport.js#L435-L458

public void Crafty.viewport.scale(Number amt)

Number amt: amount to zoom/scale in on the elements

Adjusts the scale (zoom). When amt is 1, it is set to the normal scale, e.g. an entity with this.w == 20 would appear exactly 20 pixels wide. When amt is 10, that same entity would appear 200 pixels wide (i.e., zoomed in by a factor of 10), and when amt is 0.1, that same entity would be 2 pixels wide (i.e., zoomed out by a factor of (1 / 0.1)).

If you pass an amt of 0, it is treated the same as passing 1, i.e. the scale is reset.

This method sets the absolute scale, while Crafty.viewport.zoom sets the scale relative to the existing value.

Example

Crafty.viewport.scale(2); // Zoom in -- all entities will appear twice as large.

Back to top

Crafty.viewport.scroll()

src/graphics/viewport.js#L127-L145

Crafty.viewport.scroll(String axis, Number val)

axis: 'x' or 'y'

val: The new absolute position on the axis

Will move the viewport to the position given on the specified axis

Example

Will move the camera 500 pixels right of its initial position, in effect shifting everything in the viewport 500 pixels to the left.

Crafty.viewport.scroll('_x', 500);

Back to top

Crafty.viewport.zoom()

src/graphics/viewport.js#L337-L358

public void Crafty.viewport.zoom(Number amt, Number cent_x, Number cent_y, Number time[, String|function easingFn])

Number amt: amount to zoom in on the target by (eg. 2, 4, 0.5)

Number cent_x: the center to zoom on

Number cent_y: the center to zoom on

Number time: the duration in ms of the entire zoom operation

easingFn: A string or custom function specifying an easing. (Defaults to linear behavior.) See Crafty.easing for more information.

Zooms the camera in on a given point. amt > 1 will bring the camera closer to the subject amt < 1 will bring it farther away. amt = 0 will reset to the default zoom level Zooming is multiplicative. To reset the zoom amount, pass 0.

Example

// Make the entities appear twice as large by zooming in on the specified coordinates over the duration of 3 seconds using linear easing behavior
Crafty.viewport.zoom(2, 100, 100, 3000);

Crafty.viewport

Events

Example

Properties

Methods

Crafty.viewport._scale

Crafty.viewport.bounds

See Also

Example

Crafty.viewport.clampToEntities

Crafty.viewport.y

Crafty.viewport.centerOn()

Example

Crafty.viewport.mouselook()

Crafty.viewport.x

Crafty.viewport.follow()

Example

Crafty.viewport.onScreen()

Crafty.viewport.pan()

Example

Crafty.viewport.rect()

Example

Crafty.viewport.scale()

See Also

Example

Crafty.viewport.scroll()

Example

Crafty.viewport.zoom()

Example