cocos.layer.scrolling module

This module defines the ScrollableLayer and ScrollingManager classes.

This module helps to handle what will be visible on screen when the game world does not fit in the window area.

It models this concept: the game world is a big volume. We have a camera that follows the actor moving parallel to one of the volume faces, without rotations. What the camera sees is what will be seen on the app window. Also, the camera’s movements can be restricted in order not to show parts outside of the world. This technique is usually named ‘scrolling’.

It has support for parallax rendering, that is, faking perspective by using layers that slide slower the farther they are.

The important concepts are:

  • The coordinator, implemented as ScrollingManager which enforces the view limits imposed by the managed layers, accounts for layer’s parallax.

  • The managed layers, implemented each by a ScrollableLayer, which as a group holds all the entities in the world and each one can define what area of the x-y plane should be shown on camera.

-The focus, tied to ScrollingManager fx and fy attributes, which

indicates that point (fx, fy) in world coordinates is the point of interest, and should show at the center of the screen view if no restriction is violated.

class ScrollableLayer(parallax=1)

Bases: cocos.layer.base_layers.Layer

Layer that supports scrolling.

If px_width is defined, then px_height must also be defined; scrolling will be limited to only show areas with origin_x <= x < = px_width and origin_y <= y <= px_height).

If px_width is not defined, then the layer will not limit the scrolling.

A layer may have a parallax value which is used to scale the position (and not the dimensions) of the view for the layer - the layer’s view (x, y) coordinates are calculated as:

my_view_x = parallax * passed_view_x
my_view_y = parallax * passed_view_y

The scrolling is managed by the parent node of ScrollingManager class.

Warning

Don’t change scale_x , scale_y from the default 1.0 or scrolling and coordinate changes will fail.

Parameters

parallax (float) – the parallax for this layer. Defaults to 1.

draw()

Draws itself

on_cocos_resize(usable_width, usable_height)

Event handler for window resizing.

on_enter()

Called every time just before the node enters the stage.

on_exit()

Called every time just before the node exits the stage.

set_dirty()

The viewport has changed in some way.

set_view(x, y, w, h, viewport_ox=0, viewport_oy=0)

Sets the position of the viewport for this layer.

Parameters

  • x (float) – The view x position

  • y (float) – The view y position

  • w (float) – The width of the view

  • h (float) – The height of the view

  • viewport_ox (float) – The viewport x origin

  • viewport_oy (float) – The viewport y origin

class ScrollingManager(viewport=None, do_not_scale=None)

Bases: cocos.layer.base_layers.Layer

Handles scrolling for his children, which should be ScrollableLayer instances.

Restricts the scrolling so that all the visibility restriction imposed by the children are honored; at least one child should define a constraint for the scrolling to be limited.

The drawing can be limited to a specific window’s rectangle by passing the viewport parameter.

The scrolling manager also provides coordinate changes between screen coords and world coords.

Parameters

  • viewport (Rect) – A rectangle defining the viewport. [Optional]

  • do_not_scale (bool) – Whether the ScrollingManager should scale the view during Window resizes. (Defaults to None, meaning it takes the same value as director.autoscale)

add(child, z=0, name=None)

Add the child and then update the manager’s focus / viewport.

Parameters

  • child (CocosNode) – The node to add. Normally it’s a ScrollableLayer.

  • z (int) – z-order for this child.

  • name (str) – The name of this child. [Optional]

force_focus(fx, fy)

Force the manager to focus on a point, regardless of any managed layer visible boundaries.

Parameters

  • fx (int) – the focus point x coordinate

  • fy (int) – the focus point y coordinate

on_cocos_resize(usable_width, usable_height)

Event handler for Window resize.

on_enter()

“Called every time just before the node enters the stage.

on_exit()

Called every time just before the node exits the stage.

pixel_from_screen(x, y)

deprecated, was renamed as screen_to_world

pixel_to_screen(x, y)

deprecated, was renamed as world_to_screen

refresh_focus()

Resets the focus at the focus point.

screen_to_world(x, y)

Translates screen coordinates to world coordinates.

Account for viewport, layer and screen transformations.

Parameters

  • x (int) – x coordinate in screen space

  • y (int) – y coordinate in screen space

Returns

tuple[int, int] – coordinates in world-space

set_focus(fx, fy, force=False)

Makes the point (fx, fy) show as near the view’s center as possible.

Changes his children so that the point (fx, fy) in world coordinates will be seen as near the view center as possible, while at the same time not displaying out-of-bounds areas in the children.

Parameters

  • fx (int) – the focus point x coordinate

  • fy (int) – the focus point y coordinate

  • force (bool) – If True, forces the update of the focus, eventhough the focus point or the scale did not change. Defaults to False.

set_state()

Sets OpenGL state for using scissor test.

unset_state()

Unsets OpenGL state for using scissor test.

update_view_size()

Updates the view size based on the director usable width and height, and on the optional viewport.

visit()

Draws itself and its children into the viewport area.

Same as in CocosNode.visit(), but will restrict drawing to the rect viewport.

world_to_screen(x, y)

Translates world coordinates to screen coordinates.

Account for viewport, layer and screen transformations.

Parameters

  • x (int) – x coordinate in world space

  • y (int) – y coordinate in world space

Returns

tuple[int, int] – coordinates in screen space

property scale

The scaling factor of the object.

Type

float