Estendendo componentes do SDK

Última atualização: 16 de julho de 2026

Este mecanismo permite que desenvolvedores estendam o comportamento de um componente sem modificar o componente em si.

Quando você precisa estender a funcionalidade de um componente, o PlayServ usa Handlers. Um Handler deixa você anexar lógica própria a um método do componente, sem reescrever o componente.

---

Quando estender componentes do SDK

Use a extensão de componentes quando precisar:

• adicionar regras próprias em torno de um método existente do componente — por exemplo, permitir ou negar um join
• introduzir comportamento específico do jogo em um fluxo padrão do componente
• anexar vários Handlers independentes ao mesmo ponto de extensão

---

Estender um método do componente

Exemplo: estender o método Join de um componente de Group.

// Extend the Join method
PlayServ.Server.Group("Game")
  .ExtendMethod(PlayServ.Server.Group.Join, user => {
    return false; // abort pipeline
  })

  // sugar
  .DoJoin(user => { ... });

Quando o componente executa a operação Join, o Pipeline roda assim:

1

O componente inicia

O componente começa o seu ciclo de processamento para a operação Join.

2

Os Handlers são executados

Os Handlers registrados rodam em ordem, como uma cadeia de middleware.

3

Um Handler retorna false

Se qualquer Handler retornar false, o Pipeline para imediatamente.

4

A operação é cancelada

A operação Join é cancelada e nenhum Handler seguinte roda.

aviso

Um Handler pode abortar o Pipeline de middleware. Retornar false interrompe o processamento e cancela a operação.

---

Como os Handlers são executados

Um Handler é executado como parte de um Pipeline de middleware. É isso que torna possível registrar mais de um Handler para o mesmo ponto de extensão e ainda manter cada implementação mínima.

---

Funciona em qualquer componente

Essa abordagem vale para qualquer componente. Alguns componentes reservam métodos RPC específicos na API deles e os marcam explicitamente como extensíveis. Esses métodos fazem parte do ciclo de vida do componente e são invocados pelo próprio componente sob certas condições.

observação

Alguns componentes expõem pontos de extensão explícitos, na forma de métodos RPC reservados. Esses métodos fazem parte do ciclo de vida do componente e são invocados por ele mesmo sob condições específicas.

---

Exemplo: Join controlado para uma Room de partida

Cenário: você tem uma Room de partida na qual os Players podem entrar. O client usa a chamada padrão Join(), mas o servidor precisa decidir se a entrada é permitida. Regras típicas de gameplay incluem:

• a partida já começou
• a Room está cheia
• o usuário está banido deste modo
• o usuário não atende aos requisitos de rank ou nível

Você não substitui o componente Groups nem cria um método RPC próprio à parte. Em vez disso, estende o método padrão Join e aplica regras no servidor, mantendo a chamada do client inalterada.

Fluxo:

1

O client chama Join()

O client chama Join() no Group de destino.

2

O servidor roda o Pipeline do Join

O servidor executa o Pipeline de middleware do Join, rodando cada Handler de regra registrado.

3

Uma regra falha

Se qualquer regra falhar, o Handler retorna false e o Pipeline é abortado — o join é rejeitado.

4

Todas as regras passam

Se todas as regras passarem, o join é permitido e o Handler conclui.

Cliente:

await PlayServ.Group("Game").Join();

Servidor:

PlayServ.Server.Group("Game")
  .ExtendMethod(PlayServ.Server.Group.Join, user => {

    // Gameplay checks
    bool roomIsFull = false;
    bool matchAlreadyStarted = false;
    bool userIsBanned = false;
    bool requirementsNotMet = false;

    if (roomIsFull || matchAlreadyStarted || userIsBanned || requirementsNotMet)
      return false; // abort pipeline -> Join is rejected

    return true; // allow Join to proceed
  })

  // sugar: the Join handler itself
  .DoJoin(user => {

    // Optional: actions on successful join
    // e.g. attach user to match context

    return true;  // accept user into the group
    // return false; // reject
  });

---

Próximos passos

• Groups — como os métodos extensíveis se encaixam no ciclo de vida completo do componente de Groups (Join é um exemplo)
• RPC & Server-side Game Logic — os pontos de extensão são atrelados a métodos RPC e à execução de Handlers