GameUtil 2D

A simple framework for development of games

Guia de Referncia Verso 1.1

Desenvolvido por : Luciano Alves da Silva (lucianopascal@yahoo.com.br)

Abril 2014

Creative Commons (CC) - Alguns Direitos Reservados

O pacote gameutil2d.classes.basic

Nesse pacote esto disponveis as classes bsicas teis , voltada para a exibio de imagens, construo de animaes, criao de pontos de coliso e etc. Vejamos as classes abaixo: A classe GameElement Essa uma classe genrica, utilizada como classe base para a construo das outras classes presentes dentro desse e outros pacotes desta framework. Mtodo
SetX(int value) SetY(int value) SetWidth(int value) SetHeight(int value) SetBounds(int int h) x, int y, int w,

Descrio
Mtodo responsvel por definir a posio do elemento na coordenada X da tela Mtodo responsvel por definir a posio do elemento na coordenada Y da tela Mtodo responsvel por definir a largura do elemento. Mtodo responsvel por definir a altura do elemento. Mtodo responsvel por definir a coordenada X, a coordenada Y, a largura e a altura do elemento. Desloca um elemento pela coordenada X da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o elemento para direita , caso contrrio, move para esquerda . Desloca um elemento pela coordenada Y da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o elemento para baixo , caso contrrio, move para cima . Mtodo responsvel por definir uma tag rotulo para o nosso objeto (muito til quando trabalhado com a classe Character e Scene). Mtodo responsvel por retornar a tag definida para o elemento do jogo. Mtodo responsvel por retornar a coordenada X do elemento na tela do jogo. Mtodo responsvel por retornar a coordenada Y do elemento na tela do jogo. Mtodo responsvel por retornar a largura do elemento. Mtodo responsvel por retornar a altura do elemento na tela do jogo.

MoveByX(int value)

MoveByY(int value)

SetTag(string tag) GetTag() GetX() GetY() GetWidth() GetHeight()

Mtodo
IsTouch(float x, float y)

Descrio
Mtodo que retorna verdadeiro se o elemento foi tocado na tela, baseado nas coordenadas X e Y onde ocorreu o toque. Mtodo abstrato (implementado nas classes derivadas) responsvel por desenhar o elemento na tela.

Draw(Canvas canvas)

A classe Image Essa classe (derivada da classe GameElement), responsvel por desenhar uma imagem na tela do jogo. Mtodo
Image(Context id_image, int int h) x, context, int int ,y int h,

Descrio
Construtor da classe responsvel por carregar a imagem. No parmetro do construtor informamos o nome da imagem (id_imagem), as coordenadas do elemento (parmetros x e y), a largura (w) e a altura (y). Mtodo responsvel por definir a posio da imagem na coordenada X da tela Mtodo responsvel por definir a posio da imagem na coordenada Y da tela Mtodo responsvel por definir a largura da imagem. Mtodo responsvel por definir a altura da imagem. Mtodo responsvel por definir a coordenada X, a coordenada Y, a largura e a altura da imagem. Desloca uma imagem pela coordenada X da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca a imagem para direita , caso contrrio, move para esquerda . Desloca uma imagem pela coordenada Y da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca a imagem para baixo , caso contrrio, move para cima . Mtodo responsvel por definir uma tag rotulo para o nosso objeto (muito til quando trabalhado com a classe Character e Scene). Mtodo responsvel por retornar a tag definida para a imagem do jogo. Mtodo responsvel por retornar a coordenada X da imagem na tela do jogo. Mtodo responsvel por retornar a coordenada Y da imagem na tela do jogo. Mtodo responsvel por retornar a largura da imagem. Mtodo responsvel por retornar a altura da imagem na tela do jogo.

SetX(int value) SetY(int value) SetWidth(int value) SetHeight(int value) SetBounds(int int h) x, int y, int w,

MoveByX(int value)

MoveByY(int value)

SetTag(string tag) GetTag() GetX() GetY() GetWidth() GetHeight()

Mtodo
IsTouch(float x, float y) Draw(Canvas canvas)

Descrio
Mtodo que retorna verdadeiro se a imagem foi tocada na tela, baseada nas coordenadas X e Y onde ocorreu o toque. Mtodo responsvel por desenhar a imagem na tela Mtodo responsvel por desenhar a imagem na tela, com efeito de Flip (inverso). Se o parmetro effect possuir o valor FlipEffect.HORIZONTAL, inverte a imagem na horizontal, agora se parmetro possuir o valor FlipEffect.NONE, no aplica nenhum efeito.

Draw(Canvas effect)

canvas,

FlipEffect

A classe AnimationSprites Essa classe (derivada da classe GameElement), responsvel por exibir uma animao de sprites na tela do jogo. Mtodo
AnimationSprites(Context context, int x, int ,y int h, int h)

Descrio
Construtor da classe responsvel por carregar o objeto que ira exibir a animao . No parmetro do construtor informamos o parmetro context, as coordenadas do animao (parmetros x e y), a largura (w) e a altura (y) das sprites que estaro no objeto. Mtodo responsvel por adicionar uma imagem dentro do objeto, que far parte da animao de sprites. Mtodo que inicia a animao de sprites. Nesse mtodo definimos o intervalo de troca das imagens em frames (no parmtro frames), e se a animao ocorrer em loop (caso o parmetro loop seja true) ou no (caso o parmetro loop seja false). Mtodo que encerra a animao de sprites. Mtodo responsvel por definir a posio da animao na coordenada X da tela Mtodo responsvel por definir a posio da animao na coordenada Y da tela Mtodo responsvel por definir a largura das sprites inseridas no objeto. Mtodo responsvel por definir a altura das sprites inseridas no objeto. Mtodo responsvel por definir a coordenada X, a coordenada Y, a largura e a altura da animao. Desloca uma animao pela coordenada X da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca a animao para direita , caso contrrio, move para esquerda .

Add(int Id)

Start(int frames, boolean loop)

Stop() SetX(int value) SetY(int value) SetWidth(int value) SetHeight(int value) SetBounds(int int h) x, int y, int w,

MoveByX(int value)

Mtodo
MoveByY(int value)

Descrio
Desloca uma animao pela coordenada Y da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca a animao para baixo , caso contrrio, move para cima . Mtodo responsvel por definir uma tag rotulo para o nosso objeto (muito til quando trabalhado com a classe Character e Scene). Mtodo responsvel por retornar a tag definida para a animao do jogo. Mtodo responsvel por retornar a coordenada X da animao na tela do jogo. Mtodo responsvel por retornar a coordenada Y da animao na tela do jogo. Mtodo responsvel por retornar a largura da animao. Mtodo responsvel por retornar a altura da animao na tela do jogo. Mtodo que retorna verdadeiro se a animao foi tocada na tela, baseada nas coordenadas X e Y onde ocorreu o toque. Mtodo responsvel por exibir a animao na tela Mtodo responsvel por exibir a animao na tela, com efeito de Flip (inverso). Se o parmetro effect possuir o valor FlipEffect.HORIZONTAL, inverte a animao na horizontal, agora se parmetro possuir o valor FlipEffect.NONE, no aplica nenhum efeito.

SetTag(string tag) GetTag() GetX() GetY() GetWidth() GetHeight() IsTouch(float x, float y) Draw(Canvas canvas)

Draw(Canvas effect)

canvas,

FlipEffect

A classe Collision Essa classe responsvel por verificar a coliso entre objetos dentro da tela do jogo. Mtodo
Check(GameElement GameElement obj2) obj1,

Descrio
Mtodo responsvel verificar se houve uma coliso entre dois objetos. Retorna true quando ocorrer uma coliso, e falso caso contrrio. Mtodo responsvel por verificar se houve a coliso de um objeto com algum outro elemento qualquer dentro de uma cena (ver sobre a classe Scene mais para frente), que possua uma tag especificada no parmetro (any_object_width_tag). O mtodo retorna true se ocorreu uma coliso, e falso caso contrrio. Verifica se houve a coliso de um objeto com algum outro elemento qualquer dentro de uma cena que possua uma tag especificada no parmetro (any_object_width_tag). Diferente do mtodo Check, esse retorna a instncia do elemento que colidiu com o objeto (se uma coliso acontecer). Caso nenhuma coliso tenha acontecido, o mtodo retorna null.

Check(GameElement obj1, scene, any_object_with_tag)

Scene string

CheckAndReturn(GameElement Scene scene, any_object_with_tag)

obj1, string

A classe Box Essa classe (derivada da classe GameElement), possui somente uma nica finalidade : definir pontos de coliso.

Mtodo
Box(int x, int ,y int w, int h)

Descrio
Construtor da classe responsvel por carregar os pontos de coliso, onde informamos as coordenadas X e Y, como tambm a largura e a altura. Construtor da classe responsvel por carregar os pontos de coliso, onde informamos as seguintes informaes: x,y, largura (w), altura (h) e sua tag.

Box(int x, int ,y int w, int h, string tag)

O pacote gameutil2d.classes.character
Nesse pacote existe somente uma classe, destinada para a criao de personagens (para jogos no estilo plataforma).

A classe Character Com a classe Character podemos criar personagens voltados para jogos no estilo plataforma. A classe j possui sistema de fsica (pulo e queda), deteco de colises e etc.

Mtodo
Character(Context context, x, int ,y int h, int h) int

Descrio
Construtor da classe responsvel por carregar o objeto que ira exibir o personagem . No parmetro do construtor informamos o parmetro context, as coordenadas do animao (parmetros x e y), a largura (w) e a altura (y) das sprites que estaro no objeto. Mtodo responsvel por adicionar as sprites que representam o estado de repouso de um personagem (quando o ele fica parado em movimento). Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer a aquela animao. Mtodo responsvel por adicionar as sprites que representam o movimento do personagem (que pode ser o movimento dele correndo ou andando). Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer aquela animao.

AddNewSpritesIdle(string animation_name, int...Ids)

AddNewSpritesMove(string animation_name, int...Ids)

Mtodo
AddNewSpritesAttack(string animation_name, int...Ids)

Descrio
Mtodo responsvel por adicionar as sprites que representam o ataque do personagem (que pode ser um soco, chute ou qualquer outro golpe). Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer aquela animao. Mtodo responsvel por adicionar as sprites que representam o pulo do personagem. Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer aquela animao. Mtodo responsvel por adicionar as sprites que representam o personagem sofrendo algum dano. Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer aquela animao. Mtodo responsvel por adicionar as sprites que representam o personagem morrendo. Cada animao deve possuir um nome e o conjunto de imagens que vo pertencer aquela animao. Executa a animao do personagem em estado de repouso (parado). Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem em estado de repouso (parado). Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de repouso que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem se movendo para a direita. Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem se movendo para a direita. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de movimento que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem se movendo para a esquerda. Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false).

AddNewSpritesJumping(string animation_name, int...Ids)

AddNewSpritesDamage(string animation_name, int...Ids)

AddNewSpritesDie(string animation_name, int...Ids)

Idle(string animation_name, frames, boolean loop)

int

Idle(int frames, boolean loop)

MoveToRight(string animation_name, int boolean loop)

frames,

MoveToRight(int loop)

frames,

boolean

MoveToLeft(string animation_name, int frames, boolean loop)

Mtodo

Descrio
Executa a animao do personagem se movendo para a esquerda. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de movimento que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem atacando. Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem atacando. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de ataque que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem pulando. Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem atacando. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de ataque que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem pulando. Nesse mtodo devemos informar o nome da animao, o intervalo da troca das sprites (em frames), o valor de deslocamento do pulo do personagem e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem atacando. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao de ataque que estiver dentro do personagem. Os nicos argumentos que informamos o intervalo da troca das sprites (em frames) , o valor de deslocamento do pulo do personagem e se a animao ficar em loop (true) ou no (false). Executa a animao do personagem sofrendo dano (alm de mostrar o personagem piscando na tela). Nesse mtodo devemos informar o nome da animao e o intervalo da troca das sprites (em frames).

MoveToLeft(int loop)

frames,

boolean

Attack(string animation_name, int frames, boolean loop)

Attack(int frames, boolean loop)

Jump(string animation_name, frames, boolean loop)

int

Jump (int frames, boolean loop)

Jump(string animation_name, int frames, int jump_shift, boolean loop)

Jump (int frames, int jump_shift, boolean loop)

SufferDamage(string animation_name, int frames)

Mtodo

Descrio
Executa a animao do personagem sofrendo dano (alm de mostrar o personagem piscando na tela). Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao do personagem sofrendo dano presente dentro do objeto. O nico argumento que informamos o intervalo da troca das sprites (em frames) . Executa a animao do personagem morrendo. Nesse mtodo devemos informar o nome da animao e o intervalo da troca das sprites (em frames). Executa a animao do personagem morrendo. Como nesse mtodo no informamos nenhum nome, ser executado a primeira animao do personagem morrendo presente dentro do objeto. O nico argumento que informamos o intervalo da troca das sprites (em frames) . Mtodo que retorna verdadeiro se o personagem est atacando, caso contrrio, retorna falso. Mtodo que retorna verdadeiro se o personagem est sofrendo dano, caso contrrio, retorna falso. Mtodo que retorna verdadeiro se o personagem est morrendo (quando a animao dele morrendo est em execuo), caso contrrio, retorna falso. Mtodo que retorna verdadeiro se o personagem est morto (quando a animao dele morrendo encerrada), caso contrrio, retorna falso. Mtodo que retorna verdadeiro se o personagem est no cho, caso contrrio, retorna falso. Nesse mtodo definimos em frames o tempo de durao do dano do personagem. Mtodo que retorna verdadeiro se o personagem sofreu uma coliso pelos lados com objetos que so definidos dentro do objeto presentes dentro de um cenrio. Nesse mtodo definimos os elementos (objetos) de coliso , que o nosso personagem poder se colidir durante seu movimento pelos lados. Os elementos de coliso so representados por tags (e que devero ser definidos pelo mtodo SetTag) e devero estar presentes dentro de um objeto do tipo Scene, onde o personagem estar adicionado. Nesse mtodo definimos os elementos (objetos) de coliso , que o nosso personagem poder se colidir durante uma queda aps o pulo. Os elementos de coliso so representados por tags (e que devero ser definidos pelo mtodo SetTag) e devero estar presentes dentro de um objeto do tipo Scene, onde o personagem estar adicionado.

SufferDamage(int frames)

Die(string frames)

animation_name,

int

Die(int frames)

IsAttacking() IsDamaged()

IsDying()

IsDead() IsGround() SetMaxFrameDamageDuration(int frames)

CollisionBySide(Scene scene)

AddCollisionElementOfSideByTag(string tag)

AddCollisionElementOfFallByTag(string tag)

Mtodo
Update(Scene scene)

Descrio
Mtodo responsvel por processar o pulo, a queda, as colises, o ataque e toda a fsica do personagem. Quando o mtodo Update est em uso, o mesmo processa o pulo e a queda do personagem. Esse mtodo habilita ou desabilita o pulo e queda do personagem. Esse mtodo vira nosso personagem para a direita (inverte as imagens), se o mesmo estiver em sentido contrrio. Esse mtodo vira nosso personagem para a esquerda (inverte as imagens), se o mesmo estiver em sentido contrrio. Inverte todas as sprites do personagem (realiza um efeito de flip na horizontal). Mtodo responsvel por definir a posio do personagem na coordenada X da tela Mtodo responsvel por definir a posio do personagem na coordenada Y da tela Mtodo responsvel por definir a largura do personagem. Mtodo responsvel por definir a altura do personagem. Mtodo responsvel por definir a coordenada X, a coordenada Y, a largura e a altura do personagem. Desloca um personagem pela coordenada X da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o personagem para direita , caso contrrio, move para esquerda . Desloca um personagem pela coordenada Y da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o personagem para baixo , caso contrrio, move para cima . Mtodo que retorna verdadeiro se o objeto foi tocado na tela, baseada nas coordenadas X e Y onde ocorreu o toque. Mtodo responsvel por exibir o personagem na tela. Mtodo responsvel por definir uma tag rotulo para o nosso objeto (muito til quando trabalhado com a classe Scene). Mtodo responsvel por retornar a tag definida para a imagem do jogo.

SetEnableJumpAndFall(boolean jump_fall)

TurntoRight()

TurntoLeft() InvertSprites() SetX(int value) SetY(int value) SetWidth(int value) SetHeight(int value) SetBounds(int x, int y, int w, int h)

MoveByX(int value)

MoveByY(int value)

IsTouch(float x, float y) Draw(Canvas canvas) SetTag(string tag) GetTag()

10

O pacote gameutil2d.classes.scene
Nesse pacote existe somente uma classe, destinada para a criao de cenrios do jogo.

A classe Scene Com a classe Scene podemos criar um cenrio, onde estaro todos os elementos que sero visualizados no jogo. Seu uso opcional, mas, quando for utilizar a classe Character para a construo de personagens, seu uso torna-se (teoricamente) obrigatrio.

Mtodo
Scene() Add(GameElement element) Get(int index) Remove(int index) Remove(GameElement element) GetCount() GetCountByType(string type)

Descrio
Construtor da classe Scene. Mtodo que adiciona um elemento dentro do objeto scene. Mtodo que retorna um objeto (do tipo GameElement) presente em um determinado ndice (especificado no parmetro ndex). Remove um elemento do objeto scene, baseado em seu ndice. Remove um elemento do objeto scene, baseado em sua instncia. Retorna o total de elementos dentro do objeto. Conta e retorna o total de elementos dentro do objeto de um determinado tipo de dados, informada no parmetro type. Conta e retorna o total de elementos dentro do objeto que possuem uma determinada tag, informada no parmetro tag. Mtodo que retorna um array, que contm todos os elementos presentes dentro do objeto scene. Desloca todos os elementos dentro do objeto scene pela coordenada X da tela (partindo a posio de origem de cada um). Se o valor informado no parmetro value for positivo, desloca os elementos para direita , caso contrrio, move para esquerda . Desloca todos os elementos dentro do objeto scene pela coordenada Y da tela (partindo a posio de origem de cada um). Se o valor informado no parmetro value for positivo, desloca os elementos para baixo , caso contrrio, move para cima .

GetCountByTag(string tag) Elements()

MoveByX(int value)

MoveByY(int value)

11

O pacote gameutil2d.classes.text
Nesse pacote existe somente uma classe, destinada para exibir textos (como uma hud e etc.) de um jogo.

A classe TextDrawable Com a classe TextDrawable podemos exibir uma informao na tela do jogo (ideal para a construo de uma HUD (Head-Up Display). Mtodo
TextDrawable(Context FontName font_name) SetX(int value) SetY(int value) SetXY(int x, int y) SetSize(int size) SetColor(int color) DrawString(Canvas text) canvas, string contexto,

Descrio
Construtor da classe TextDrawable. Define a posio na coordenada X onde iremos exibir o texto. Define a posio na coordenada Y onde iremos exibir o texto. Define a posio nas coordenada X e Y onde iremos exibir o texto. Definimos o tamanho do texto a ser exibido na tela. Define a cor do texto a ser exibido na tela. (Usar a classe Color) Exibe seu texto na tela do seu jogo. Desloca o texto pela coordenada X da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o texto para direita , caso contrrio, move para esquerda . Desloca o texto pela coordenada Y da tela (partindo a posio de origem do mesmo). Se o valor informado no parmetro value for positivo, desloca o texto para baixo , caso contrrio, move para cima .

MoveByX(int value)

MoveByY(int value)

12

O pacote gameutil2d.project
Esse o pacote onde o desenvolvedor poder colocar as suas classes que sero utilizadas dentro do seu jogo. Nesse pacote, existe a seguinte e nica classe:

A classe GameMain Essa a classe principal, onde o desenvolvedor ir escrever o cdigo do seu jogo. A classe est dividida pelos seguintes mtodos:

public GameMain(Context context) {

O mtodo GameMain o construtor da nossa classe e o primeiro mtodo que executado. Normalmente utilizado para a inicializao de variveis de controle, alguns objetos e etc.

public void onScreenLoading(int w, int h, OrientationMode orientation) { }

O mtodo onScreenLoading executado logo aps o mtodo GameMain. Nesse mtodo podemos obter a largura e a altura da tela do dispositivo, assim tambm como sua orientao (pelo parmetro orientation). Nesse mtodo podemos carregar todos os objetos (como imagens por exemplo), que dependam das informaes da tela do dispositivos para serem instanciadas.
public void Update() { }

O mtodo Update utilizado para o processamento de toda a lgica do jogo (coliso, movimento, aes e etc.). Sua execuo ocorre sempre, em cada frame.

13

public void Draw(Canvas canvas) { }

O mtodo Draw utilizado para desenhar todos os elementos na tela do jogo (atravs do uso do parmetro canvas). Sua execuo ocorre em cada frame.

public void onTouch(MotionEvent event) { }

O mtodo onTouch disparado toda vez que ocorre algum toque na tela do dispositivo, e todas as informaes a respeito do toque ficam armazenado no parmetro event.

Onde colocar as imagens (e sprites) que sero utilizadas no jogo ???

Todas as imagens que forem ser utilizadas no jogo, devem estar dentro do diretrio drawable-mdpi, presente dentro da pasta res do seu projeto.

Faam bom uso da Framework.

14