Documentação

⚠️ Aviso: Gameeky ainda está em estágios iniciais de desenvolvimento e, portanto, as coisas estão sujeitas a alterações.

📝 Nota: Este documento não é um tutorial completo sobre tudo o que Gameeky pode fazer, mas deve fornecer instruções suficientes para começar.

Tópicos

  1. Introdução
  2. Instalação
  3. Pacotes temáticos
  4. Visão geral
  5. O lançador
  6. O reprodutor
  7. Jogo cooperativo
  8. O editor de cenas
  9. O editor de entidades
  10. O editor de código e o código tipo LOGO
  11. Plugins

Introdução

Gameeky permite que jovens alunos e educadores criem e explorem jogos cooperativos e experiências de aprendizagem. Mais especificamente, permite:

📝 Nota: Esta é uma ferramenta de aprendizagem em forma de motor de jogo. Não é um motor de jogo profissional. Se você está procurando uma ferramenta para criar videogames profissionais, considere o motor de jogo Godot.

Instalação

O método de instalação recomendado é através da central de softwares do sistema como, por exemplo, o GNOME Software. Procure por Gameeky e instale-o. Alternativamente, ele também pode ser instalado a partir do Flathub. Da mesma forma, pesquise Gameeky e siga as instruções do site.

Por fim, ele também pode ser instalado a partir do terminal:

flatpak --user install flathub dev.tchx84.Gameeky

Pacotes temáticos

Gameeky fornece pacotes de blocos de construção predefinidos para diferentes interesses como, por exemplo, um jogo de RPG agrícola ambientado em um mundo de fantasia medieval. Um pacote temático contém:

Esses blocos de construção podem ser reutilizados para criar cenas personalizadas, novos jogos e muitos materiais de aprendizagem.

O método de instalação recomendado é através da central de software do sistema como, por exemplo, GNOME Software. Os pacotes temáticos são oferecidos como complementos na página do centro de software. Alternativamente, também pode ser instalado a partir do Flathub. Da mesma forma, pacotes temáticos são oferecidos como complementos do site. Selecione o complemento e siga as instruções do site.

Por fim, os pacotes também podem ser instalados a partir do terminal:

flatpak --user remote-ls flathub | grep dev.tchx84.Gameeky.ThematicPack
flatpak --user install flathub dev.tchx84.Gameeky.ThematicPack.FreedomValley

Visão geral

O pacote Gameeky fornece cinco componentes principais:

  1. O lançador é o principal componente onde todos os pacotes temáticos e projetos podem ser encontrados e lançados.
  2. O reprodutor é onde os jogos podem ser jogados e participados.
  3. O editor de cenas é onde as cenas podem ser criadas e editadas.
  4. O editor de entidades é onde as entidades podem ser criadas e editadas.
  5. O editor de código é onde a experiência do tipo LOGO pode ser obtida.

O lançador

O lançador serve como ponto de partida do Gameeky. Ele fornece uma maneira fácil de gerenciar pacotes temáticos instalados como complementos e projetos localizados no diretório ~/Gameeky. O gerenciador oferece suporte para todas as operações básicas de gerenciamento:

Compartilhando projetos

O lançador oferece uma maneira simples de compartilhar projetos. Para exportar um projeto, siga estas etapas:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Exportar.
  2. Siga as instruções do diálogo.

Para importar um projeto, siga estas etapas:

  1. No lançador, acesse o menu e selecione a opção Importar.
  2. Siga as instruções do diálogo.

O reprodutor

O reprodutor fornece uma representação visual do mundo do jogo e os meios para interagir com esse mundo.

Para iniciar um jogo, clique no botão Jogar do projeto no inicializador. Isso iniciará a cena padrão para esse projeto. Cada pacote temático e projeto vem com uma cena padrão. Para reproduzir outras cenas do mesmo projeto, siga estes passos:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Jogar.
  2. No reprodutor, acesse o menu e selecione a opção Novo.
  3. Na caixa de diálogo de criação, selecione o arquivo de cena e clique no botão Criar.

Elementos de tela do jogo

Uma vez no jogo, a cena ocupa a maior parte da tela, mas também existem outros elementos.

O HUD é uma interface colocada na parte inferior central da tela. Este elemento é usado para visualizar as estatísticas do personagem do usuário. É composto pelas seguintes partes:

Outro elemento é o visualizador de diálogos. Este visualizador é colocado na parte inferior da tela e é usado para exibir diálogos do jogo como, por exemplo, uma mensagem de um personagem do jogo ou do narrador. É composto pelas seguintes partes:

Controles

Uma vez no jogo, o personagem do usuário pode ser controlado com dois métodos:

Ações

O personagem do usuário pode realizar diversas ações para interagir com o mundo do jogo:

Salvar arquivos

O estado do jogo pode ser salvo a qualquer momento e restaurado posteriormente. Os arquivos salvos são cópias completas da cena e, portanto, arquivos de cena regulares.

  1. Para salvar o estado do jogo, vá ao menu e selecione a opção Salvar como….
  2. Para restaurar o estado do jogo, siga os mesmos passos descritos acima para abrir uma cena.

Jogo cooperativo

Gameeky foi projetado desde o início para criar e compartilhar experiências cooperativas. Todos os jogos criados com ele podem ser jogados cooperativamente. Não há requisitos especiais. Embora não haja limite teórico quanto ao número de usuários que podem ingressar em um jogo cooperativo, existem limitações técnicas. Por exemplo, recursos de computação limitados.

Para iniciar um jogo cooperativo, siga estas etapas:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Jogar.
  2. No reprodutor, acesse o menu e selecione a opção Novo.
  3. Na caixa de diálogo de criação, aumente o número de participantes e clique no botão Criar.

Para participar de um jogo cooperativo:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Jogar.
  2. No reprodutor, acesse o menu e selecione a opção Entrar.
  3. Na caixa de diálogo de ingresso, especifique o endereço IP do usuário que iniciou o jogo cooperativo e clique no botão Entrar.

📝 Nota: Todos os usuários que aderirem a um jogo cooperativo deverão possuir uma cópia do mesmo pacote temático ou projeto.

📝 Nota: Cenas personalizadas criadas a partir de pacotes temáticos não precisam ser compartilhadas. A cena é compartilhada automaticamente durante o jogo, desde que todos os usuários compartilhem o mesmo pacote temático.

📝 Nota: Os usuários podem participar de uma sessão como qualquer entidade definida no pacote temático, por exemplo, como uma árvore ou uma pedra. Para fazer isso, expanda a seção Avançado da caixa de diálogo de criação ou associação e selecione um Tipo de entidade diferente.

O editor de cenas

O editor de cenas permite aos usuários criar e modificar mundos de jogo. Ele serve como a forma inicial e mais simples de experiência de criação sem código no Gameeky.

Para editar uma cena existente, clique no botão Editar do projeto no inicializador. Para criar uma nova cena é recomendado iniciar um projeto existente, como um pacote temático. Siga estas etapas para adicionar uma nova cena:

  1. No lançador, clique no botão Opções do projeto e seleciona a opção Editar.
  2. No editor de cenas, vá ao menu e selecione a opção Novo.

📝 Nota: Pacotes temáticos não podem ser modificados. Portanto, uma cópia editável deve ser criada. No menu de opções do pacote temático, selecione a opção Copiar.

Conceitos

Uma cena é uma coleção de entidades organizadas em uma grade de blocos. As propriedades básicas de uma cena são:

Fluxo de trabalho

O fluxo de trabalho de edição de cenas se assemelha ao de uma ferramenta de pintura. As entidades são pintadas e removidas da cena. As etapas básicas para editar uma cena são as seguintes:

  1. Para adicionar entidades à cena, selecione uma entidade no painel esquerdo e coloque-a na cena clicando em um bloco na grade.
  2. Para remover entidades da cena, selecione a ferramenta Remover à esquerda e clique no bloco da entidade na grade.
  3. Embora as entidades venham com propriedades e comportamentos predefinidos, entidades específicas na cena podem ser personalizadas. Selecione a ferramenta Editar no painel esquerdo e clique no bloco da entidade na grade.
  4. Para testar a cena, vá ao menu e selecione a opção Experimentar.

Além disso, o editor de cenas fornece ajudantes para facilitar as coisas, como:

Dicas e truques

Para uma experiência aprimorada, tente as seguintes dicas e truques:

O editor de entidades

O editor de entidades permite aos usuários criar e modificar objetos e criaturas do jogo. Ele fornece uma experiência mais profunda de criação sem código, pois requer a compreensão dos sistemas subjacentes do Gameeky.

Antes de criar uma nova entidade do zero, é recomendável inspecionar as entidades existentes nos pacotes temáticos. Portanto, para inspecionar uma entidade existente siga estes passos:

  1. No editor de cenas, clique com o botão direito em uma entidade no painel esquerdo.
  2. Selecione a opção Editar no menu.

Para criar uma nova entidade:

  1. No editor de cenas, clique com o botão direito em qualquer lugar do painel esquerdo.
  2. Selecione a opção Adicionar no menu.

Conceitos

As entidades representam tudo o que pode existir no jogo, por exemplo, a grama, o personagem do usuário, uma fonte de luz, a música de fundo e até mesmo a lógica do jogo. Uma entidade é composta de três partes:

  1. Propriedades lógicas do jogo.
  2. Gráficos.
  3. Sons.

Propriedades lógicas do jogo

Essas propriedades determinam como as entidades se comportam e interagem com outras entidades, por exemplo, diferentes combinações dessas propriedades determinarão se uma entidade está agindo como uma pedra estática ou como um inimigo vivo.

Embora existam duas dúzias de propriedades, algumas delas requerem atenção especial aqui:

📝 Nota: Ao criar um novo pacote temático suponha que a entidade com número identificador 1 será atribuída ao personagem do usuário no jogo.

Gráficos

As entidades são representadas na tela através de gráficos 2D, que podem ser estáticos ou animados.

Esses gráficos são atribuídos a combinações específicas de estado e direção, por exemplo, uma animação específica será renderizada quando uma entidade estiver Movendo para o Oeste, enquanto outra animação será renderizada quando a mesma entidade estiver como Ocioso para * Sul*.

Todas as entidades devem fornecer um gráfico Padrão, por exemplo, para visualizá-lo no editor de cenas ou depurar plugins.

Sons

Da mesma forma que os gráficos, as entidades podem emitir sons quando estão em estados específicos, por exemplo, o som de passos é reproduzido quando a entidade está Movendo. As direções não importam aqui.

Não há sons Padrão, pois os sons são opcionais.

Fluxo de trabalho

O fluxo de trabalho de criação de entidades é semelhante ao preenchimento de um formulário ou modelo. A entidade mais básica é criada com as seguintes etapas:

  1. Na aba Jogo, comece a definir os valores de cima para baixo. Observe que todas as propriedades fornecem seus próprios padrões. Apenas o identificador é obrigatório. É recomendado definir um nome para que seja mais fácil encontrar a entidade no editor de cenas.
  2. Na guia Gráficos, clique no botão Adicionar para criar a primeira animação padrão. Deixe Estado e Direção como Padrão. Expanda a seção Detalhes da animação padrão para selecionar uma imagem. Clique no botão Visualizar para inspecionar a imagem selecionada.
  3. Salve a entidade e use-a no editor de cenas.

Dicas e truques

Para uma experiência aprimorada, tente as seguintes dicas e truques:

Ter suporte para jogos cooperativos abre a porta para cooperadores que podem ser controlados com código. Para conseguir isso, Gameeky fornece uma pequena biblioteca que permite aos usuários controlar uma única entidade usando Python, em uma experiência semelhante ao LOGO.

Fluxo de trabalho

Siga estas etapas para iniciar um jogo cooperativo:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Jogar.
  2. No reprodutor, acesse o menu e selecione a opção Novo.
  3. Na caixa de diálogo de criação, aumente o número de participantes e clique no botão Criar.

Para entrar no jogo com código, estas etapas devem ser seguidas:

  1. No lançador, clique no botão Opções do projeto e selecione a opção Jogar.
  2. No reprodutor, acesse o menu e selecione a opção Entrar com código.
  3. Escreva o código Python que usa a biblioteca Gameeky, veja os exemplos abaixo.
  4. Clique no botão Jogar.

Exemplos

Entrar e sair de um jogo:

from gameeky.library import Game

game = Game()
game.join()
game.quit()

Realizar ações:

from gameeky.library import Game, Direction

game = Game()
game.join()
game.update()

game.idle(time=1000)
game.move(Direction.EAST, time=1000)
game.move(Direction.WEST, time=1000)
game.take(time=1000)
game.use(time=1000)
game.drop(time=1000)
game.interact(time=1000)

game.quit()

Inspecionar a posição e as propriedades básicas da entidade do personagem do usuário:

from gameeky.library import Game

game = Game()
game.join()
game.update()

print(game.entity.position.x, game.entity.position.y)

game.quit()

Inspecionar o estado da cena:

from gameeky.library import Game

game = Game()
game.join()
game.update()

for entity in game.scene.entities:
    print(entity.position.x, entity.position.y)

game.quit()

📝 Nota: Os cooperadores só podem ver o ambiente imediato da cena, não a cena completa.

Inspecionar as estatísticas avançadas da entidade do personagem do usuário:

from gameeky.library import Game

game = Game()
game.join()
game.update()

print(game.stats.durability, game.stats.stamina, game.stats.held)

game.quit()

Dicas e truques

Para uma experiência aprimorada, tente as seguintes dicas e truques:

Plugins

Os atuadores podem modificar o comportamento de uma entidade. Uma única entidade pode usar vários atuadores para modelar comportamentos mais complexos. Embora exista uma ampla variedade de atuadores predefinidos, o resultado final é limitado quando comparado ao código real.

Portanto, Gameeky fornece suporte para atuadores criados pelo usuário irem além do que os atuadores predefinidos podem fazer.

Conceitos

Existem três tipos de atuadores:

  1. Atuadores regulares atuam em cada tique da cena, por exemplo, para mover a entidade para um local aleatório em cada tique.
  2. Atuadores ativáveis atuam apenas em intervalos de tempo fixos ou quando ativados explicitamente por outra entidade, por exemplo, para fazer surgir um novo inimigo para a cena a cada cinco segundos.
  3. Atuadores interativos atuam quando outras entidades interagem com sua entidade, por exemplo, para teletransportar uma entidade para um local diferente quando essa entidade interage com um portal.

Todos os atuadores usam suas próprias propriedades de entidades de jogo para modificar seu comportamento:

Fluxo de trabalho

Para criar um novo atuador, siga as etapas:

  1. Abra um novo documento em um editor de texto.
  2. Escreva uma classe de atuador, veja os exemplos abaixo.
  3. Salve o novo documento em ~/Gameeky/NOME_PROJETO/actuators/NOME_ATUADOR.py
  4. No editor de entidade, vá na guia Jogo para a seção de atuadores.
  5. Uma nova opção chamada NOME_ATUADOR será exibida junto com os atuadores predefinidos.
  6. Selecione-o e salve a entidade no disco.

📝 Nota: Atuadores criados pelo usuário também podem ser acessados no editor de cenas ao personalizar entidades específicas.

Exemplos

Uma classe mínima atuador:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        pass

Inspecionar a entidade:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        print(self.entity.name)

Executar uma ação na entidade:

from gameeky.plugins import Actuator as Plugin
from gameeky.common.definitions import Action, Direction

class Actuator(Plugin):
    def tick(self) -> None:
        self.entity.perform(Action.MOVE, Direction.SOUTH)

Enviar um diálogo para a entidade:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        self.entity.tell("Hello...")

Inspecionar todas as outras entidades sentadas bem na frente da entidade:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.obstacles:
            print(entity.name)

Inspecionar todas as outras entidades que compartilham a mesma posição que a entidade:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.surfaces:
            print(entity.name)

Inspecionar todas as outras entidades que cercam a entidade:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.surroundings:
            print(entity.name)

📝 Nota: O método surroundings leva em consideração a propriedade Raio da entidade.

Inspecionar todas as entidades na cena, que não são estáticas:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.scene.mutables:
            print(entity.name)

Inspecionar todas as entidades controladas pelos usuários:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.scene.playables:
            print(entity.name)

Criar um atuador que atua a cada cinco segundos:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    activatable = True

    def tick(self) -> None:
        if not self.ready:
            return

        print("Activated...")

        super().tick()

📝 Nota: A propriedade ready leva em consideração a propriedade Taxa da entidade.

Criar um atuador que atua somente quando interagido pelos usuários:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    interactable = True

    def prepare(self, interactee: "Entity") -> bool:
        if interactee.playable is False:
            return False

        return super().prepare(interactee)

    def tick(self) -> None:
        if self.interactee is None:
            return

        print(f"Interacted with {self._interactee.name}")

        super().tick()

Para exemplos mais complexos, verifique o diretório actuators predefinido do Gameeky.

Dicas e truques

Para uma experiência aprimorada, tente as seguintes dicas e truques: