v0.6.4 - ?

- clean-up automatic event registration #268, #269

- fix RichLabel keyword halign to align, #258

New in cocos 0.6.4

- MapColliders classes changed API to be more useful and clear: collision between actors and tiles and between actors and TmxObject are easier to handle

- Supports the variants 'csv', 'xml', 'base64(uncompressed)' for Tiled Editor layer data

- Simpler Scene and Layer code for automatic window events registration

- Particle systems now accepts per-instance texture

- Better IDEs autocompletion: by being more specific in cocos code imports, IDEs can work faster and be more selective with the autocompletion offerings.

- Support for pyglet 1.3

Be sure to read about compatibility changes in the docs, there has been some api changes.

Api changes and other compatibility notes from previous version

cocos 0.6.4

-----------

This is the first release supporting pyglet 1.3+

Imports in cocos library are more specific, so user code that were doing

``from cocos.somemodule import *`` may fail to find some symbols.

To fix that user code, add explicit exports as needed.

MapColliders classes changed API to be more useful and clear.

- MapColliders moved to his own module, 'mapcolliders'.

- RectMapCollider was renamed to RectMapWithPropsCollider.

- The new RectMapCollider handles a simpler collision case, when all tiles

are solid: now no need to set cells properties to signal a cell border should

not be walked over.

- TmxObjectMapCollider now handles AABB collision with any TmxObject that

can be loaded.

Rect.intersects() now it only intersects iff some interior points overlaps

Removed Scene methods push_all_handlers() and remove_all_handlers()

In ScrollingManager two methods had been renamed, the old name still valid but

will be removed in future:

- pixel_from_screen() -> screen_to_world()

- pixel_to_screen() -> world_to_screen()

Compatibility Notes

====================

.. toctree::

:maxdepth: 1

compatibility_notes

mapcoliders

Map Colliders

=============

Overview

--------

If a scene has an actor moving, we may update its position from frame to frame

using the discrete approximation::

velocity = velocity + acceleration * dt

position = position + velocity * dt

That's fine when the actor does not find an obstacle, like a wall.

If there is an obstacle, we usually want to

- stop the position change so the actor touches the obstacle but does

not overlap it

- do something sensible with the velocity (stop ?, bounce ?)

- maybe do some action based on which obstacle (spikes ?, glass ?)

To do this we can represent the actor and the obstacles as rects with sides

parallel to the axis, and do the calculations.

This is what 'map colliders' do::

- with the actor velocity, rect before, tentative rect after

- with a 'map layer' that groups a number of obstacles

it will

- Properly update velocity and position

- Call appropriate methods when it detects actor bumped into an obstacle

- Tell if any collision in the x and / or y axis happened

While some mapcolliders are meant to be used in tiled maps (RectMapCollider,

RectMapWithPropsCollider), others (TmxObjectMapCollider) can be used with no

tiles at all.

Properly update velocity and position

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

the position and velocity update can be written as::

vx, vy = actor.velocity

# using the player controls, gravity and other acceleration influences

# update the velocity

vx = (keyboard[key.RIGHT] - keyboard[key.LEFT]) * actor.MOVE_SPEED

vy += GRAVITY * dt

if actor.on_ground and keyboard[key.SPACE]:

vy = actor.JUMP_SPEED

# with the updated velocity calculate the (tentative) displacement

dx = vx * dt

dy = vy * dt

# get the player's current bounding rectangle

last = actor.get_rect()

# build the tentative displaced rect

new = last.copy()

new.x += dx

new.y += dy

# account for hitting obstacles, it will adjust new and vx, vy

actor.velocity = mapcollider.collide_map(maplayer, last, new, vx, vy)

# update on_ground status

actor.on_ground = (new.y == last.y)

# update player position; player position is anchored at the center of the image rect

actor.position = new.center

How velocity changes in a collision is handled by method mapcollider.on_bump_handler;

it can be set to custom code or to one of the stock handlers:

- on_bump_bounce(): Bounces when a wall is touched.

- on_bump_stick(): Stops all movement when any wall is touched. (sticky bomb...)

- on_bump_slide(): Blocks movement only in the axis that touched a wall. (player...)

For convenience, a stock handler can be specified at instantiation time with

the 'velocity_on_bump' parameter.

Call appropriate methods when it detects actor bumped into an obstacle

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When mapcollider.collide_map detects that actor collides with obj 'someobj' from

side 'someside', it will call mapcollider.collide_<someside>(someobj).

There 'someside' is one of 'left', 'right', 'top' and 'bottom'.

This provides an opportunity to do things based on which object the actor touched,

like 'spike' ? -> init spikes animation and kill actor.

Notice that each mapcollider.collide_* can receive multiple calls in the same

mapcollider.collide_map call.

Tell if any collision in the x and / or y axis happened

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After collide_map returns, the flags mapcollider.bumped_x and mapcollider.bumped_y

tells if there's have been any collision along the respective axis.

This can be handy to flip actor's animation animation direction, by example from

'walk_left' to 'walk_right'

Variants

---------

Currently they are three map colliders variants,

RectMapCollider

^^^^^^^^^^^^^^^

Obstacles are rectangular tiles grouped into a RectMapLayer; all non empty cells

are deemed solid.

:class:`implementation <cocos.mapcolliders.RectMapCollider>`

RectMapWithPropsCollider

^^^^^^^^^^^^^^^^^^^^^^^^

Obstacles are rectangular tiles grouped into a RectMapLayer, cells use properties

"left", "right", "top" and "bottom" to signal which side(s) block movements.

A solid block would probably have all four sides set; a platform can set

only the top so the player might jump up from underneath and pass through.

For convenience these properties would typically be set on the tiles

themselves, rather than on individual cells. Of course for the cell which

is the entrance to a secret area you could override a wall's properties to

set the side to False and allow ingress.

See :ref:`cell_properties_label` for information about properties.

:class:`implementation <cocos.mapcolliders.RectMapWithPropsCollider>`

TmxObjectMapCollider

^^^^^^^^^^^^^^^^^^^^

Obstacles are TmxObjects grouped into a TmxObjectLayer, each object is meant

to block movement.

A common use case is to do moving platforms in a platform game.

:class:`implementation <cocos.mapcolliders.TmxObjectMapCollider>`

How to use

-----------------------

There are basically two ways to include this functionality into an

actor class

- as a component, essentially passing (mapcollider, maplayer) in

the actor's __init__

- mixin style, by using RectMapCollider or a subclass as a secondary

base class for actor.

Component way is more decoupled, Mixin style is more powerful because

the collision code will have access to the entire actor trough his 'self'.

To have a working instance the behavior of velocity in a collision must be

defined, and that's the job of method `on_bump_handler`

- if one of the stock on_bump_<variant> suits the requirements, suffices

`mapcollider.on_bump_handler = mapcollider.on_bump_<desired variant>`

or passing a selector at instantiation time

`mapcollider = MapCollider(<desired variant>)`

- for custom behavior define on_bump_handler in a subclass and instantiate it.