PicoPicoEngine English Documentation

picopico_english_docs.txt

Here is an English translation of the PicoPicoEngine's documentation.

ppgame:start()

Call ppgame:start(fn) to change the function that the engine calls to update your game.
By default, the engine will call your function called "start" but you can update this at run time based on your game logic.
For example, you might call ppgame:start(mainmenu) and then later ppgame:start(play) and then ppgame:start(gameover).
The argument you pass is a lua closure.

ppgame:platform()

Returns a string that identifies which platform your game is running on.

ppgame:fps()

Returns the number of frames per second that your game is running at right now.
This is useful for debugging.  See also ppgame:deltaTime()

ppgame:deltaTime()

Returns the elapsed time in seconds since the last game loop iteration.
For example, at 60 fps, ppgame:deltaTime() will return 1/60 = 0.01667

ppgame:mouse()

Returns the position of the mouse pointer as a pppoint.
This only works on the desktop, not iOS.

ppgame:volume(value)

Sets the master volume of the MML audio engine.
If you don't pass a parameter, ppgame:volume() will return the current volume.
Volume ranges from 0 = silent up to 1.0 for full volume.

ppgame:setNumber(name, value)
ppgame:setInteger(name, value)
ppgame:setString(name, value)

You can save values between game sessions.  This is useful for saving high scores,
or your character in an RPG.

ppgame:getNumber(name)
ppgame:getInteger(name)
ppgame:getString(name)

Get values that have been previously saved with setNumber, setInteger and setString.
If no value has been set, null is returned.

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

ppgraph:tileInfo({tile info})

This configures the graphics system so that it understands the layout of your tile texture.
With no arguments, it retrieves the current settings.  If you provide a table as described below you can override the layout.
This is useful if you want to mix different sizes of sprites.

You only need to call this if you want to change from the default.  Normally,
DotEditor will set this up for you automatically.  There is a similar function on ppmap.

{
  size={width=width of each tile in pixels,height=height of each tile in pixels},
  stride={x=horizontal spacing of the tiles,y=vertical spacing of the tiles},
  offset={x=starting position of the next tile,y=vertical start position of the tile}
}

ppgraph:put({x,y},tile,name,{texture option},{r,g,b,a})
ppgraph:put({x,y},tile,{texture option},{r,g,b,a})

Draws a tile from your tile set onto the screen.  You must specify the x,y to
draw to and which tile you want.  Tiles are numbered 1, 2, 3, etc from left to right
starting at the top left in your tile set.  You can override the texture options or tint the tile with a color.

ppgraph:pos({x,y})
ppgraph:locate({x,y})

Sets the position for other drawing text with the ppgraph:print() function.
If you omit the argument, then the current position is returned.
As with most functions that take an {x,y} argument, you can either pass a pppoint,
or an {x,y} pair or two arguments x and y.

ppgraph:move({x,y})

Moves the drawing position by the specified offset.  See also ppgraph:pos()

ppgraph:print(string,{r,g,b,a})

Draws a string onto the screen at the current drawing position (see ppgraph:pos) with the given color.
The bitmap font used supports alphanumeric, Hiragana and Katakana only.
If you omit the color argument, then the current color from ppgraph:color() is used.

ppgraph:color({r,g,b,a})

Sets the current drawing color.  If you omit the argument, then the current color
is returned.

ppgraph:scale({x,y})

Sets the current scale factor for drawing.  The default is {1.0,1.0}.
If you omit the argument, the current scale factor is returned.

ppgraph:flip(hflip,vflip,rot90)

Modifies drawing so that sprites are flipped horizontally, vertically and/or rotated by 90 degrees.
If you omit the arguments, then the current settings are returned.

ppgraph:rotate(angle)

Sets the current rotation angle for drawing text and tiles.  Angle is measured in radians.
If you omit the argument, then the current rotation value is returned.

ppgraph:alpha(value)

Sets the current transparency for drawing.  Alpha values range from 0 = transparent to 1.0 = opaque.
If you omit the argument, then the current alpha value is returned.

ppgraph:fill({x,y,width,height},{r,g,b,a})

Draws a filled rectangle on the screen.  If you omit the color, then the current color from ppgraph:color() is used.

ppgraph:box({x,y,width,height},{r,g,b,a})

Draws the outline of a rectangle on the screen.  If you omit the color, then the current color from ppgraph:color() is used.

ppgraph:line({x,y},{x,y},{r,g,b,a})

Draws a line from {x,y} to {x,y} on the screen.  If you omit the color, then the current color from ppgraph:color() is used.

ppgraph:layout({x,y,width,height},centerx,centery,area)

Computes coordinates laid out within an area.  You can ask for the result to
be centered in x and/or y by passing "true" for the centerx and/or centery parameters.
If you pass "false" for them, then the x or y you give is relative to the edges, so you
can place things on the left, right, top or bottom by using positive or negative values.
If you omit the area parameter, then the screen area is used instead.

ppgraph:update()

Refreshes the screen from within the game loop.
You can choose to either return from your game loop function to cause a redraw, or
call this to update the screen explicitly.  See also ppgame:start()
See the example game projects to see both ways of working.

ppgraph:pivot({x,y})

Specifies the center position for rotation and scaling.  If you omit the argument,
the current pivot position is returned.

ppgraph:lineWrap(flag)

When text goes off the screen, this flag determines whether it should wrap around
or not.

ppgraph:append({display object})

Registers a display object which will be drawn every frame of the game loop.
{display object} must be a table with a draw() method, like ppsprite.

ppgraph:remove({display object})

Unregisters a display object was previously registered with ppgraph:append().
That object will no longer be drawn by the game loop.

ppgame:tileRect(tile,{texture})

Computes the bounding rectangle of a given tile in the texture.  If texture is omitted then
the default texture is used.

ppgraph:stretch(rect,tile,{edge},{texture})

Draws a tile to the screen, like ppgraph:put, but allows you to stretch the tile to a different size.
You can pass a {x,y,width,height} or a pprect.  If you pass an edge argument, then a border of that many pixels will not be stretched.

ppgraph.white={255,255,255}
ppgraph.red={255,0,0}
ppgraph.green={0,255,0}
ppgraph.blue={0,0,255}
ppgraph.yellow={255,255,0}
ppgraph.cyan={0,255,255}
ppgraph.magenta={255,0,255}
ppgraph.black={0,0,0}
ppgraph.gray={96,96,96}
ppgraph.lightgray={188,188,188}
ppgraph.orange={255,128,0}
ppgraph.skin={255,216,160}
ppgraph.darkgreen={56,104,0}
ppgraph.lightgreen={152,232,0}
ppgraph.brown={120,64,0}

15 predefined constant colors for your convenience.  These can be used anywhere that an {r,g,b,a} is listed.

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

ppfont:loadTTF(ttffont, fontname, size)

Read a TrueType Font, as identified by the given fontname.  Can only be used on the desktop, not in DotEditor.

ppfont:loadTexture(texture, fontname, width, height)

Load the given texture as a font.  Can only be used on the desktop, not in DotEditor.

ppfont:set(name)

Select the font you want to use by name.  You can choose between "half", "mini", or "default" or a font you have loaded with other ppfont API.

ppfont:height()

Get the height of the current font in pixels.

ppfont:width(string)

Get the width in pixels of the given string if it is drawn in the current font.
This is handy for centering or positioning text exactly.

ppfont:size(string)

Compute the bounding rectangle of a string if it is drawn in the current font.

ppfont:texture()

Returns the texture for the currently selected font.

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

ppkey.up()
ppkey.down()
ppkey.left()
ppkey.right()
ppkey.a()
ppkey.b()
ppkey.c()
ppkey.d()
ppkey.e()
ppkey.f()
ppkey.g()
ppkey.h()

Each of these functions returns true or false if the matching key is pressed.
This works as expected on the desktop, but also on iOS if you are using an iCade device.