Apêndice G - Pergaminhos resolvidos

Gabaritos comentados dos “Desafios da Masmorra”.

Este apêndice reúne soluções de referência para os Desafios e Boss Finais espalhados pelos 37 capítulos. Use como bússola, não como caminho único. Cada problema aceita várias respostas certas; as daqui são apenas uma forma de chegar lá, escolhidas para reforçar os conceitos do capítulo correspondente.

Os pergaminhos seguem a ordem dos capítulos - dos primeiros desafios em Dart puro (Capítulo 1) até a síntese final do jogo completo (Capítulo 37). Se você tiver uma proposta de solução mais elegante, envie pelo formulário em /beta-readers.

Parte I - A Primeira Tocha

Capítulo 1 - Seu primeiro programa Dart

▸ Desafio 1.1 - Personalize o banner

Modifique o banner para incluir o seu nome como autor. Use uma nova variável autor e interpolação de string para exibi-la. Dica: use múltiplas linhas de print() para deixar o banner legível.

A ideia é praticar dois conceitos do capítulo de uma vez só: declarar variável com var e usar interpolação com cifrão. O resto é cosmético, decidir como o banner fica bonito.

// lib/main.dart
void main() {
  var nomeJogo = 'Masmorra ASCII';
  var versao = '0.1.0';
  var autor = 'Aventureiro Anônimo';

  print('');
  print('═══════════════════════════════════════');
  print('       $nomeJogo v$versao');
  print('       por $autor');
  print('═══════════════════════════════════════');
  print('');
  print('  Prepare-se para explorar');
  print('  o desconhecido.');
  print('');
  print('═══════════════════════════════════════');
  print('');
}

Quando rodar com dart lib/main.dart, o banner sai centralizado mais ou menos no mesmo lugar do original. Note que $autor é interpolação simples (uma variável). Para expressões maiores existe ${expr}, mas no banner não precisa.

Variação opcional: troque o nome hardcoded por leitura do teclado. Isso é assunto do Capítulo 2, então pode deixar para depois sem culpa.

▸ Desafio 1.2 - Explore o dart analyze

Introduza três erros diferentes no código (tipo errado, variável não usada, ponto e vírgula faltando) e veja como o dart analyze os reporta. Depois corrija todos. Observe como o analisador ajuda você a encontrar problemas sem executar o programa.

Adicione as três linhas problemáticas em qualquer ordem dentro do main() e rode dart analyze. O analisador cospe uma mensagem para cada erro, com arquivo e linha. A diferença interessante está nas categorias: erro de tipo aparece como error (impede execução), variável não usada aparece como info (apenas lembrete de limpeza), e ponto e vírgula faltando volta como error sintático.

void main() {
  int x = 'texto';        // error: 'String' não cabe em 'int'
  var naoUsada = 42;      // info: variável declarada e nunca lida
  print('teste')          // error: ; faltando no fim
}

Depois de ver as três mensagens, apague as linhas e rode dart analyze de novo. O retorno limpo (No issues found!) é o feedback positivo que você quer ver antes de cada commit.

O analisador é a primeira linha de defesa contra bugs em Dart. Com strict-casts: true no analysis_options.yaml, ele fica ainda mais rigoroso. Acostume-se a rodar dart analyze antes de cada commit; muitos bugs morrem antes mesmo do programa rodar.

▸ Desafio 1.3 - Moldura com caracteres box-drawing

Reescreva o banner usando os caracteres ╔, ╗, ╚, ╝, ║ e ═ para criar uma moldura completa. A moldura deve ter largura fixa de 40 caracteres. Execute e veja o resultado alinhado.

Largura fixa de 40 significa: linha de topo com ╔, depois 38 caracteres ═, depois ╗. As linhas de meio começam com ║, terminam com ║, e precisam de 38 caracteres no miolo (texto somado a espaços de preenchimento). O truque é forçar a largura com padRight(38), que adiciona espaços à direita até completar.

void main() {
  var nomeJogo = 'Masmorra ASCII';
  var versao = '0.1.0';

  print('╔══════════════════════════════════════╗');
  print('║' + ' $nomeJogo v$versao'.padRight(38) + '║');
  print('║' + ''.padRight(38) + '║');
  print('║' + '  Prepare-se para explorar'.padRight(38) + '║');
  print('║' + '  o desconhecido.'.padRight(38) + '║');
  print('╚══════════════════════════════════════╝');
}

Atenção a uma armadilha: padRight(38) não trunca. Se o texto passar de 38 caracteres, a moldura estoura. No banner inicial todos os textos cabem com folga, mas quando o jogo crescer e a moldura precisar lidar com nomes de jogador longos, vale extrair uma função utilitária que trunca ou quebra linhas. Por enquanto, simples assim resolve.

▸ Desafio 1.4 - Múltiplas linhas com quebra de linha

Em vez de usar vários print(), tente criar uma única string multilinha usando \n ou aspas triplas ('''). Execute e compare qual abordagem você acha mais legível no código.

As duas formas produzem saída idêntica. A diferença é estética. Com \n o código fica numa linha só (longa, ruim para diff e para mente que está lendo). Com aspas triplas, o código preserva a forma visual do banner no próprio arquivo, o que ajuda quando você revisa.

void main() {
  var banner = '''
═══════════════════════════════════
       Masmorra ASCII v0.1.0
═══════════════════════════════════

  Prepare-se para explorar
  o desconhecido.

═══════════════════════════════════
''';
  print(banner);
}

Aspas triplas vencem quando o conteúdo tem várias linhas; \n continua útil para mensagens curtas, de uma ou duas linhas. Pequena armadilha: a quebra de linha logo depois da abertura ''' faz parte da string. Se incomodar, coloque o primeiro caractere de conteúdo grudado em ''', sem ENTER intermediário. Aí a saída começa exatamente onde você escolheu.

⚔ Boss Final 1.5 - ASCII art de portal mágico

Crie uma arte ASCII de um portal mágico ou de uma inscrição antiga na parede da masmorra, usando apenas print(). Comece simples (5-10 linhas) e incremente. Teste caracteres especiais: ◆, ◊, ✦, ✧ para efeitos visuais. O objetivo é dominar a saída no terminal e entender como texto visual funciona num roguelike.

Desafio aberto, sem solução única. A graça é tentar até gostar do resultado. Comece com um esboço grosseiro num editor de texto monoespaçado (sem fonte proporcional, senão você sofre com alinhamento). Depois transcreva linha por linha como print. Não tenha medo de espaços; eles são parte do desenho.

void main() {
  print('');
  print('         ✦ ✧ ✦');
  print('       ✧ ◆◊◆ ✧');
  print('      ✦ ╔═══╗ ✦');
  print('        ║ ◊ ║');
  print('        ║   ║');
  print('        ╚═══╝');
  print('       ✦ ✧ ✦ ✧');
  print('');
  print('   "Aqui se cruzam os mundos."');
  print('');
}

◆ (diamante cheio) e ◊ (diamante vazio) dão peso visual quando alternados; ✦ e ✧ ficam ótimos como faíscas ou estrelas pequenas. Se o terminal mostrar quadradinhos em vez do glifo, a fonte do terminal não tem o caractere desenhado. Troque para JetBrains Mono, Fira Code ou Source Code Pro, que são as fontes recomendadas em todo o livro.

Uma sugestão de prática: depois do portal, tente desenhar uma chave, uma poção ou um pequeno dragão. Cada um exige resolver um problema diferente de alinhamento, e isso prepara o terreno para o Capítulo 6, onde a arte ASCII vira parte estruturada do jogo, com StringBuffer no lugar dos vários print().

Capítulo 2 - Conversando com o terminal

▸ Desafio 2.1 - Pergunta extra (classe do personagem)

Depois de pedir o nome, pergunte a classe do personagem (Guerreiro, Mago ou Ladrão) e inclua essa informação na saudação. Crie uma função pedirClasse() que retorna String. Valide que a entrada é uma das três opções válidas.

A função vai precisar fazer três coisas: imprimir o prompt, ler a resposta, e verificar se cabe nas três opções. Como o capítulo ainda não introduziu if, use o operador de coalescência ?? para dar fallback quando a entrada não bate com nenhuma das opções esperadas. Para garantir comparação justa, normalize a entrada com .toLowerCase().trim() antes de testar.

import 'dart:io';

String pedirClasse() {
  stdout.write('Escolha sua classe (Guerreiro, Mago, Ladrão): ');
  var entrada = (stdin.readLineSync() ?? '').trim().toLowerCase();

  var classes = ['guerreiro', 'mago', 'ladrão', 'ladrao'];
  var indice = classes.indexOf(entrada);

  // Se a entrada bateu, devolve a forma canônica com inicial maiúscula.
  // Senão, devolve a classe padrão (Aprendiz).
  if (indice == -1) return 'Aprendiz';
  if (indice == 3) return 'Ladrão';
  return entrada[0].toUpperCase() + entrada.substring(1);
}

void main() {
  stdout.write('Qual é o seu nome? ');
  var nome = stdin.readLineSync() ?? 'Aventureiro';
  var classe = pedirClasse();
  print('Bem-vindo, $nome o $classe!');
}

Aceitar ladrao sem acento é cortesia ao jogador que digita rápido. O indexOf devolve o índice se achar, ou -1 se não, e isso vira o caminho de decisão. Quando o leitor chegar ao Capítulo 3, pode trocar essa lógica por switch com pattern matching, que fica ainda mais limpo. Por enquanto, indice em lista resolve.

▸ Desafio 2.2 - Moldura dinâmica

Escreva uma função exibirEmMoldura(String texto) que recebe qualquer texto e o exibe dentro de uma moldura com bordas box-drawing. A moldura deve se ajustar dinamicamente ao tamanho do texto. Dica: use texto.length para saber o tamanho e '═' * n para repetir o caractere.

A largura interna da moldura precisa ser pelo menos o tamanho do texto somado a duas margens de espaço (uma de cada lado). A linha de topo e de baixo ficam com o caractere ═ multiplicado por essa largura. Em Dart, o operador * aplicado a uma String repete a string n vezes, como '═' * 10 gera dez caracteres.

void exibirEmMoldura(String texto) {
  var larguraInterna = texto.length + 2;
  var linha = '═' * larguraInterna;

  print('╔$linha╗');
  print('║ $texto ║');
  print('╚$linha╝');
}

void main() {
  exibirEmMoldura('Bem-vindo, Aventureiro');
  exibirEmMoldura('Curto');
  exibirEmMoldura('Texto bem mais longo para testar o ajuste dinâmico');
}

Cada chamada produz uma moldura com tamanho exato para o conteúdo. Variação útil: aceitar um parâmetro largura opcional que força largura mínima (assim molduras consecutivas podem ficar alinhadas mesmo com conteúdos diferentes). Outra variação: aceitar uma lista de strings em vez de uma só, e cada linha vira uma linha da moldura. A lógica é a mesma, só que a largura interna é o tamanho da maior string.

▸ Desafio 2.3 - Validação de entrada robusta

Modifique pedirNome() para recusar nomes com menos de 2 caracteres ou mais de 20. Se o jogador digitar algo fora desse intervalo, mostre uma mensagem clara de erro, sugira um intervalo válido, e peça novamente em vez de usar nome padrão. Dica: use nome.length na condição e considere um loop.

Como o capítulo ainda não apresentou while, dá para resolver com recursão: a própria função se chama de novo quando a entrada é inválida. Funciona perfeitamente para validação de poucos retries (não há risco de estourar a pilha com input humano lento). Quando o leitor chegar ao Capítulo 3, pode reescrever com while (true) e break, mais idiomático em Dart.

import 'dart:io';

String pedirNome() {
  stdout.write('Qual é o seu nome (2 a 20 caracteres)? ');
  var nome = (stdin.readLineSync() ?? '').trim();

  if (nome.length < 2) {
    print('Nome curto demais. Tente de novo (mínimo 2 caracteres).');
    return pedirNome();
  }
  if (nome.length > 20) {
    print('Nome longo demais. Tente de novo (máximo 20 caracteres).');
    return pedirNome();
  }
  return nome;
}

void main() {
  var nome = pedirNome();
  print('Bem-vindo, $nome!');
}

O .trim() evita aceitar espaços em branco no início ou fim, que contam no .length e confundem o jogador. Sem ele, ” ” (um espaço) passaria como nome de 1 caractere, e ” A ” viraria nome de 5. Pequeno detalhe que economiza dor de cabeça depois. Quando esse padrão evoluir para o Capítulo 3, a recursão vira while (true) { ...; if (válido) break; }, e o leitor vê de perto a diferença de estilo.

▸ Desafio 2.4 - Múltiplas salas com navegação

Crie três funções: descreverPraca(), descreverCorredor(), descreverPorta(). Dependendo do comando que o jogador digitar na praça, chame a função correspondente. O programa ainda aceita um único comando e termina, mas a ideia de navegar entre descrições já começa a surgir. Observe como a lógica começa a ficar mais complexa.

Cada função é um pequeno bloco de prosa narrativa com print. O main lê uma palavra do jogador e usa coalescência para escolher qual função chamar. Outra forma é usar if/else if, mas como o capítulo introduz ?? e ainda não introduziu if, dá para resolver com um Map<String, Function> onde a chave é o comando e o valor é a função a chamar.

import 'dart:io';

void descreverPraca() {
  print('A Praça Central está vazia. Você ouve passos distantes.');
  print('Saídas: norte (corredor), leste (porta de madeira).');
}

void descreverCorredor() {
  print('O corredor é estreito e escuro. As paredes são de pedra úmida.');
  print('Algo brilha no chão, ao longe.');
}

void descreverPorta() {
  print('A porta de madeira tem inscrições gastas pelo tempo.');
  print('Ela range quando você se aproxima.');
}

void main() {
  descreverPraca();
  stdout.write('Para onde você vai (norte / leste / ficar)? ');
  var rumo = (stdin.readLineSync() ?? '').trim().toLowerCase();

  var rotas = {
    'norte': descreverCorredor,
    'n': descreverCorredor,
    'leste': descreverPorta,
    'l': descreverPorta,
  };

  var proxima = rotas[rumo];
  if (proxima != null) {
    proxima();
  } else {
    print('Você fica na praça, observando o silêncio.');
  }
}

O Map<String, Function> é uma forma muito limpa de despachar comandos quando você ainda não tem switch no bolso. Quando o capítulo 12 chegar e o livro apresentar o sistema de parser com enums e sealed classes, esse padrão vira a versão definitiva. Por enquanto, mapa de funções já dá leveza ao código sem cair em sequência longa de if.

⚔ Boss Final 2.5 - Diálogo com NPC (Velho Sábio)

Adicione um comando especial "falar" que inicia uma conversa com um NPC chamado Velho Sábio na Praça Central. O Velho Sábio faz uma pergunta ao jogador (por exemplo: “Qual é a sua maior virtude?” com opções “coragem”, “sabedoria”, “justiça”) e responde com uma observação diferente para cada escolha. Integre isso ao fluxo principal: depois de responder, o programa termina com uma mensagem final do Velho Sábio.

A conversa vira uma função falarComSabio() que faz uma pergunta, lê a resposta, e despacha entre três caminhos. A função final do programa imprime uma fala de despedida. Como ainda não temos switch, um Map<String, String> mapeia virtude para resposta. Para deixar o diálogo com mais vida, use travessão antes de cada fala do Sábio, que é a convenção do português para discurso direto.

import 'dart:io';

void falarComSabio() {
  print('');
  print('O Velho Sábio se vira lentamente para você.');
  print('— Qual é a sua maior virtude, aventureiro?');
  print('  (coragem, sabedoria, justiça)');
  stdout.write('> ');
  var virtude = (stdin.readLineSync() ?? '').trim().toLowerCase();

  var respostas = {
    'coragem':   'Coragem sem prudência é apenas tropeço apressado.',
    'sabedoria': 'Sabedoria pesa, mas é o único peso que cabe no inventário.',
    'justiça':   'Quem busca justiça com pressa, encontra vingança por engano.',
    'justica':   'Quem busca justiça com pressa, encontra vingança por engano.',
  };

  var resposta = respostas[virtude] ?? 'O caminho que escolhe é seu, e só seu.';
  print('— $resposta');
  print('');
  print('— Vá, e que o silêncio do corredor te ensine.');
}

void main() {
  print('Você chega à Praça Central. Um Velho Sábio descansa sob uma árvore seca.');
  stdout.write('O que você faz (falar / ir embora)? ');
  var acao = (stdin.readLineSync() ?? '').trim().toLowerCase();

  if (acao == 'falar') {
    falarComSabio();
  } else {
    print('Você ignora o Velho Sábio e segue caminho. Ele apenas sorri.');
  }
}

O travessão — antes das falas é a forma clássica do português para diálogo direto, diferente do inglês que usa aspas. Funciona bem no terminal e dá um ar de literatura clássica ao jogo. Cada virtude aceita a forma com e sem acento, o que torna o jogo mais gentil com o teclado do jogador. Em capítulos futuros, o NPC vai ganhar memória entre conversas, dependência de inventário e dezenas de falas; por enquanto, três respostas e uma despedida já fazem o personagem parecer vivo.

Capítulo 3 - Decisões e repetições

▸ Desafio 3.1 - Contador de turnos

Adicione uma variável turno que começa em 1 e incrementa a cada vez que o jogador escolhe uma opção válida (não sair, não ajuda). Mostre o turno atual no prompt: "[Turno 5] > ". Isso simula a passagem de tempo na masmorra.

A regra é simples: incrementar turno só nas opções que representam ação no mundo (mover, lutar, explorar), e deixar opções de inventário ou ajuda como “neutras”. O incremento fica dentro do ramo do switch que corresponde a cada ação válida.

import 'dart:io';

void main() {
  var turno = 1;
  var rodando = true;

  while (rodando) {
    stdout.write('[Turno $turno] > ');
    var opcao = (stdin.readLineSync() ?? '').trim();

    switch (opcao) {
      case '1':
        print('Você explora os corredores escuros.');
        turno++;
        break;
      case '2':
        print('Você descansa. O tempo passa.');
        turno++;
        break;
      case 'ajuda':
      case '?':
        print('Opções: 1 explorar, 2 descansar, 0 sair.');
        // ajuda não conta turno, é meta-ação
        break;
      case '0':
        rodando = false;
        break;
      default:
        print('Não entendi. Digite "ajuda" para ver opções.');
    }
  }

  print('Você passou $turno turnos na masmorra.');
}

A ordem importa: imprima o turno antes de ler o comando, para que o jogador veja o número atual quando decide. Se incrementar antes da leitura, o display vai estar sempre um passo à frente da realidade. Quando o jogo crescer (no capítulo 7), turno vai migrar para um objeto EstadoJogo junto com HP, ouro e localização.

▸ Desafio 3.2 - Menu com mais opções (Ver mapa)

Adicione a opção “4, Ver mapa” que imprime um mapa ASCII simples fixo da masmorra. Por enquanto, o mapa pode ser um retângulo com # (paredes) e . (chão vazio). Use o mesmo padrão de switch/case para processar a opção.

A função exibirMapa() desenha o mapa com vários print ou com uma string única em aspas triplas. O switch ganha mais um case que chama essa função.

void exibirMapa() {
  print('  ╔══════════════════╗');
  print('  ║ ###########  ###║');
  print('  ║ #.........#  #.#║');
  print('  ║ #....@....####.#║');
  print('  ║ #.........#....#║');
  print('  ║ ###########....#║');
  print('  ║           ######║');
  print('  ╚══════════════════╝');
  print('  @ = você   # = parede   . = chão');
}

void main() {
  var rodando = true;
  while (rodando) {
    stdout.write('Opção (1-4, 0 sair): ');
    var opcao = (stdin.readLineSync() ?? '').trim();
    switch (opcao) {
      case '1': print('Explorar...');     break;
      case '2': print('Descansar...');    break;
      case '3': print('Ver inventário.'); break;
      case '4': exibirMapa();             break;
      case '0': rodando = false;          break;
      default:  print('Não entendi.');
    }
  }
}

O @ no centro do mapa marca a posição do jogador. Por enquanto é fixo; no Capítulo 15, o mapa passa a ser uma grade List<List<Tile>> e a posição do @ muda com WASD. Este desafio é o ensaio visual: o leitor já tem o vocabulário de tiles na cabeça quando chegar a hora.

▸ Desafio 3.3 - HP que diminui (simulando perigo)

Declare var hp = 100; no início. Cada vez que o jogador escolher explorar, reduza o HP em um valor fixo (por exemplo, 10-20 pontos de dano simulado). Mostre o HP atualizado no status. Se HP chegar a 0 ou menos, encerre o jogo com uma mensagem de derrota.

Uma constante de dano fixo já basta para sentir o conceito. Depois de aplicar o dano, verifica se hp <= 0; nesse caso, sai do loop com uma mensagem de derrota.

import 'dart:io';

void main() {
  var hp = 100;
  var rodando = true;

  while (rodando && hp > 0) {
    stdout.write('[HP $hp] > ');
    var opcao = (stdin.readLineSync() ?? '').trim();

    switch (opcao) {
      case '1':
        print('Você explora. Algo te machuca no escuro.');
        hp -= 15;
        break;
      case '2':
        print('Você descansa por um turno.');
        // sem dano, mas também sem cura aqui
        break;
      case '0':
        rodando = false;
        break;
      default:
        print('Opção inválida.');
    }

    if (hp <= 0) {
      print('');
      print('O escuro venceu. HP chegou a 0.');
      print('Você morre na masmorra após resistir até onde pôde.');
    }
  }
}

Note o while (rodando && hp > 0): a condição composta garante que tanto a saída voluntária quanto a morte interrompem o loop. Variação interessante: trocar o dano fixo por aleatório com Random().nextInt(15) + 5, que dá 5 a 19 de dano. Isso é tema do Capítulo 17, quando entram as sementes e a aleatoriedade controlada.

▸ Desafio 3.4 - Confirmação ao sair (dupla verificação)

Quando o jogador escolher sair (opção 0), pergunte “Tem certeza (s/n)?” de forma clara. Se digitar s, sim, ou y (yes), saia de verdade. Caso contrário, volte ao menu.

Use uma função auxiliar confirmar(String pergunta) que devolve bool. Ela aceita várias formas afirmativas (s, sim, y, yes) e considera qualquer outra coisa como “não”. Isso evita despedidas acidentais por uma tecla pressionada por engano.

import 'dart:io';

bool confirmar(String pergunta) {
  stdout.write('$pergunta (s/n): ');
  var resposta = (stdin.readLineSync() ?? '').trim().toLowerCase();
  return resposta == 's' || resposta == 'sim' ||
         resposta == 'y' || resposta == 'yes';
}

void main() {
  var rodando = true;
  while (rodando) {
    stdout.write('> ');
    var opcao = (stdin.readLineSync() ?? '').trim();
    if (opcao == '0') {
      if (confirmar('Tem certeza que quer sair?')) {
        rodando = false;
      } else {
        print('Continuando...');
      }
    } else {
      print('Opção: $opcao');
    }
  }
  print('Até a próxima descida.');
}

A função confirmar é pequena, mas vai ser reusada em vários momentos do jogo: confirmar gastar todo o ouro numa compra, confirmar usar o último item de cura, confirmar abandonar a sala do boss. Quando o capítulo 23 introduzir a loja, confirmar reaparece sem mudar uma linha.

⚔ Boss Final 3.5 - Painel de estatísticas finais

Ao final do jogo (sair confirmado ou morte), exiba um painel com nome do herói, total de turnos, HP final, dano sofrido (100 − HP final) e nota final (S, A, B, C) baseada em turnos/HP. Use ternários para determinar a nota e box-drawing para tornar o painel visual.

A nota é o coração do desafio: aninhar ternários para mapear turnos/HP em letras. Como o objetivo é mostrar ternários, mantenha uma única expressão encadeada em vez de várias if/else if.

String avaliarNota(int turnos, int hp) {
  return (turnos >= 30 && hp >= 60) ? 'S'
       : (turnos >= 20 && hp >= 40) ? 'A'
       : (turnos >= 10)             ? 'B'
       :                              'C';
}

void exibirPainel(String nome, int turnos, int hp) {
  var dano = 100 - hp;
  var nota = avaliarNota(turnos, hp);

  print('╔════════════════════════════════╗');
  print('║       FIM DA JORNADA           ║');
  print('╠════════════════════════════════╣');
  print('║ Herói:     ${nome.padRight(20)}║');
  print('║ Turnos:    ${turnos.toString().padRight(20)}║');
  print('║ HP final:  ${hp.toString().padRight(20)}║');
  print('║ Dano:      ${dano.toString().padRight(20)}║');
  print('║ Nota:      ${nota.padRight(20)}║');
  print('╚════════════════════════════════╝');
}

void main() {
  // exemplo de uso ao terminar o loop principal:
  exibirPainel('Aldric', 24, 55);
}

padRight(20) força largura fixa nas células, mantendo a borda direita alinhada independente do conteúdo. A nota encadeada pode ser lida de cima para baixo: a primeira condição verdadeira ganha. É legível, mas ternários aninhados perdem clareza rápido quando passam de três níveis; nesse ponto, vale a pena migrar para switch ou if/else if explícito. Quando o capítulo 25 introduzir XP e níveis, esse painel ganha mais campos (XP acumulado, nível, capítulos visitados) e provavelmente vira uma classe Resultado com método imprimir().

Capítulo 4 - Null safety, o escudo contra crashes

▸ Desafio 4.1 - Validação de nome robusta

Reescreva pedirNome() para recusar nomes com menos de 2 caracteres ou mais de 20. Se inválido, mostre exatamente o motivo (“Muito curto”, “Muito longo”) e peça novamente em vez de usar um padrão. Use promoção de tipo dentro de um if (entrada != null) para garantir segurança.

Solução de referência. A função vira um laço que insiste até receber algo aceitável. A peça-chave é o if (entrada != null): dentro desse bloco, o Dart promove o tipo de String? para String, e aí entrada.trim() e entrada.length ficam disponíveis sem ! ou ?.. As mensagens de erro precisam ser específicas o suficiente para o jogador entender o que está acontecendo: dizer só “inválido” frustra; “muito curto, precisa de 2 letras” educa.

import 'dart:io';

String pedirNome() {
  while (true) {
    stdout.write('Qual seu nome, aventureiro? ');
    var entrada = stdin.readLineSync();

    if (entrada != null) {
      var nome = entrada.trim();

      if (nome.length < 2) {
        print('Muito curto. Use pelo menos 2 letras.');
      } else if (nome.length > 20) {
        print('Muito longo. Use no máximo 20 letras.');
      } else {
        return nome;
      }
    } else {
      print('Não captei nada. Tente de novo.');
    }
  }
}

A armadilha clássica é esquecer o trim() e deixar passar espaços em branco como nome válido. Outra é validar entrada.length direto sobre o String? sem promoção de tipo, o que o Dart recusa em modo null-safe. Em variações futuras, pode-se rejeitar caracteres especiais com RegExp(r'^[a-zA-ZáéíóúÁÉÍÓÚãõâêôÃÕÂÊÔç ]+$') para manter o tom medieval.

▸ Desafio 4.2 - Menu com confirmação bilateral

Crie uma função confirmar(String mensagem) -> bool que mostra a mensagem, aceita s/sim/y/yes para verdadeiro e n/não/no para falso. Se o jogador digitar algo inválido, repita a pergunta. Use ?? para proteger readLineSync().

Solução de referência. O segredo é normalizar a entrada antes de comparar: toLowerCase().trim() mata variações como “Sim”, ” sim ”, “SIM ”. O operador ?? cobre o caso em que readLineSync() devolve null (entrada vazia em alguns terminais), tratando como “tente de novo” em vez de derrubar o programa. Devolver bool (não int nem String) deixa a função encaixar direto em qualquer if, mantendo o código de quem chama limpo.

import 'dart:io';

bool confirmar(String mensagem) {
  const sim = {'s', 'sim', 'y', 'yes'};
  const nao = {'n', 'não', 'nao', 'no'};

  while (true) {
    stdout.write('$mensagem (s/n) ');
    var resposta = (stdin.readLineSync() ?? '').toLowerCase().trim();

    if (sim.contains(resposta)) return true;
    if (nao.contains(resposta)) return false;

    print('Responda com s ou n.');
  }
}

void main() {
  if (confirmar('Deseja entrar na caverna?')) {
    print('Você avança bravamente.');
  } else {
    print('Você recua, prudente.');
  }
}

Usar Set ({...}) em vez de List para sim e nao torna a busca por contains em tempo constante - irrelevante para 4 elementos, mas é o tipo certo do ponto de vista semântico (sem duplicatas, sem ordem). Uma armadilha sutil: se você usar == direto com cada variação, vai escrever uma cadeia gigantesca de ||; o Set.contains mantém a função respirável quando aceitar “claro”, “ok”, “talvez não” entrar na lista.

▸ Desafio 4.3 - Interpretação de comandos em três níveis

Implemente um parser que reconheça três formas do mesmo comando: numeração (1), palavra completa (explorar) e abreviação (e). Use int.tryParse() para tentar número primeiro, depois ?? para tentar palavra, depois ?? para tentar abreviação. Demonstre com explorar/e/1.

Solução de referência. Pense no parser como uma cadeia de tentativas: primeiro testa se a entrada é um número (índice no menu), se não for, testa se bate com a palavra cheia, e por último com a abreviação. O ?? encaixa essas tentativas naturalmente porque cada etapa devolve String? - se acertou, devolve o comando canônico; se não, devolve null para a próxima tentativa pegar.

const comandos = ['explorar', 'inventario', 'descansar', 'sair'];
const abreviacoes = {'e': 'explorar', 'i': 'inventario', 'd': 'descansar', 's': 'sair'};

String? porNumero(String entrada) {
  var idx = int.tryParse(entrada);
  if (idx == null) return null;
  if (idx < 1 || idx > comandos.length) return null;
  return comandos[idx - 1];
}

String? porPalavra(String entrada) {
  return comandos.contains(entrada) ? entrada : null;
}

String? porAbreviacao(String entrada) {
  return abreviacoes[entrada];
}

String? interpretar(String entrada) {
  var limpa = entrada.toLowerCase().trim();
  return porNumero(limpa) ?? porPalavra(limpa) ?? porAbreviacao(limpa);
}

void main() {
  for (var teste in ['explorar', 'e', '1', 'EXPLORAR ', 'xyz']) {
    print('"$teste" -> ${interpretar(teste) ?? "desconhecido"}');
  }
}

Saída esperada: explorar, explorar, explorar, explorar, desconhecido. O ganho dessa estrutura é que cada estratégia mora numa função própria; adicionar uma quarta (sinônimos, por exemplo) é encaixar mais um ?? no final. A armadilha é deixar int.tryParse retornar índice sem checar limites - acessar comandos[99] derruba o jogo com RangeError. Outra é esquecer o toLowerCase, e aí “Explorar” não casa com “explorar”.

▸ Desafio 4.4 - Função parametrizada pedirTexto

Escreva String pedirTexto(String prompt, {int minLength = 1, int maxLength = 50}) com parâmetros nomeados e valores padrão. A função repete até receber um texto com tamanho válido. Use texto.length e lance exceção (ou retorne padrão) se sair do intervalo.

Solução de referência. Parâmetros nomeados com {} deixam quem chama escolher o que customizar e o que aceitar com padrão. Para pedirTexto('Nome:'), os limites são 1 e 50; para pedirTexto('Bio:', maxLength: 200), só o teto muda. Validar logo na entrada (em vez de devolver e validar fora) concentra a lógica num lugar só - o resto do código pode confiar que o retorno está dentro do contrato.

import 'dart:io';

String pedirTexto(
  String prompt, {
  int minLength = 1,
  int maxLength = 50,
}) {
  while (true) {
    stdout.write('$prompt ');
    var entrada = (stdin.readLineSync() ?? '').trim();

    if (entrada.length < minLength) {
      print('Curto demais (mínimo $minLength caracteres).');
      continue;
    }
    if (entrada.length > maxLength) {
      print('Longo demais (máximo $maxLength caracteres).');
      continue;
    }
    return entrada;
  }
}

void main() {
  var titulo = pedirTexto('Título do diário:', minLength: 3, maxLength: 30);
  var corpo = pedirTexto('Conteúdo:', maxLength: 200);
  print('"$titulo" salvo com ${corpo.length} caracteres.');
}

A escolha entre lançar exceção e repetir o prompt depende do contexto: aqui, como é entrada interativa, repetir é mais amigável - o jogador erra, lê o motivo, tenta de novo. Exceção faz sentido em camadas de domínio (parsing de save, leitura de config), onde quem chama precisa decidir o que fazer com erro. Armadilha comum: trocar >= por > (ou vice-versa) sem perceber. Se minLength: 3, a comparação correta é length < 3 (rejeita 0, 1, 2; aceita 3+).

⚔ Boss Final 4.5 - Cadeia de null safety (Sala inicial)

Crie um mapa representando três salas: salaPraca, salaCorredo, salaTesouraria, cada uma como String?. Algumas salas podem ser null (não existem). Implemente um getter salaAtual() -> String que usa encadeamento ?? para sempre garantir que o jogador está em uma sala válida, caindo para “Praça Central” se tudo mais for null. Demonstre que o encadeamento funciona mesmo com múltiplos níveis de null.

Solução de referência. O ?? brilha quando você tem várias fontes alternativas para um mesmo valor e quer “a primeira que não for nula”. Pense num jogo onde o jogador pode estar carregando uma sala de save, ou uma sala de teleporte, ou - no pior caso - voltou para a praça inicial porque tudo o mais fracassou. O encadeamento a ?? b ?? c ?? padrão lê de cima para baixo: pega o primeiro não nulo, ignora o resto.

class Mundo {
  String? salaPraca;
  String? salaCorredor;
  String? salaTesouraria;

  String salaAtual() {
    return salaPraca
        ?? salaCorredor
        ?? salaTesouraria
        ?? 'Praça Central';
  }
}

void main() {
  var mundo = Mundo();

  // tudo null -> fallback
  print(mundo.salaAtual());  // Praça Central

  // só a tesouraria existe
  mundo.salaTesouraria = 'Tesouraria do Rei';
  print(mundo.salaAtual());  // Tesouraria do Rei

  // corredor e tesouraria existem; corredor vem primeiro
  mundo.salaCorredor = 'Corredor das Tochas';
  print(mundo.salaAtual());  // Corredor das Tochas

  // tudo preenchido; praça ganha porque está primeiro na cadeia
  mundo.salaPraca = 'Praça do Mercado';
  print(mundo.salaAtual());  // Praça do Mercado
}

O detalhe importante é que o último elo da cadeia precisa ser não-anulável ('Praça Central' literal) para o tipo de retorno ser String, não String?. Se você escrever salaPraca ?? salaCorredor ?? salaTesouraria sem o literal final, Dart infere String? e quem chama precisa lidar com null de novo - perdendo justamente a garantia que esse padrão promete. Em variações com class Sala, a mesma técnica funciona devolvendo a primeira Sala não-nula; a regra é: a cadeia só vale se o último elo for sólido.

Capítulo 5 - Coleções, o inventário do herói

▸ Desafio 5.1 - Expandir o mundo (Mais salas)

Adicione pelo menos duas salas novas ao mapa: por exemplo, “Câmara do Tesouro” e “Biblioteca Antiga”. Conecte-as ao mundo existente com saídas apropriadas e descrições atmosféricas. Teste navegando até elas e verificando se as saídas funcionam nos dois sentidos.

Solução de referência. Adicionar salas novas é o exercício mais didático do capítulo, porque mostra que o “mundo” é só um Map<String, Map> - dados, não código. A regra de ouro é manter saídas simétricas: se a Praça leva ao norte para a Câmara, a Câmara precisa levar ao sul para a Praça. Quebrar essa simetria deixa o jogador “preso” e cria bugs difíceis de rastrear.

final mundo = <String, Map<String, dynamic>>{
  'praca': {
    'nome': 'Praça Central',
    'descricao': 'Uma praça empoeirada com uma fonte seca no centro.',
    'saidas': {'norte': 'camara', 'leste': 'biblioteca'},
    'itens': <String>['Moeda de Ouro'],
  },
  'camara': {
    'nome': 'Câmara do Tesouro',
    'descricao': 'Ouro empilhado até o teto, mas algo te observa nas sombras.',
    'saidas': {'sul': 'praca'},
    'itens': <String>['Gema Rubra', 'Coroa de Prata'],
  },
  'biblioteca': {
    'nome': 'Biblioteca Antiga',
    'descricao': 'Estantes inclinadas, cheiro de pergaminho úmido. Um livro brilha.',
    'saidas': {'oeste': 'praca'},
    'itens': <String>['Tomo Arcano'],
  },
};

void descreverSala(String chave) {
  var sala = mundo[chave]!;
  print('== ${sala['nome']} ==');
  print(sala['descricao']);
  var saidas = (sala['saidas'] as Map).keys.join(', ');
  print('Saídas: $saidas');
}

Para testar simetria sem rodar o jogo inteiro, escreva um pequeno validador: para cada sala, para cada saída, confira que a sala destino tem alguma saída de volta para a origem. Esse hábito vira reflexo quando o mapa cresce para 20+ salas. Outra variação útil é dar a cada sala um campo 'visitada': false que fica true na primeira entrada - útil para conquistas e mapeamento progressivo (cap. 9 vai usar isso).

▸ Desafio 5.2 - Largar itens

Implemente o comando "largar <item>" que remove um item do inventário e o coloca na sala atual (adicionando à lista de itens da sala). Valide que o jogador realmente possui o item antes de largá-lo. Dica: é exatamente o inverso de pegarItem.

Solução de referência. A simetria entre pegar e largar é o que torna o mundo “real” - o item não some, só muda de container. O cuidado é validar três coisas antes de mexer: o jogador possui o item, o argumento não está vazio, e a sala existe. Usar removeWhere ou remove em vez de um índice manual evita bugs quando há itens repetidos no inventário.

bool largarItem(String item, String salaAtual, List<String> inventario) {
  if (item.trim().isEmpty) {
    print('Largar o quê? Especifique um item.');
    return false;
  }

  // .firstWhere com orElse retorna '' se não achar
  var encontrado = inventario.firstWhere(
    (i) => i.toLowerCase() == item.toLowerCase(),
    orElse: () => '',
  );

  if (encontrado.isEmpty) {
    print('Você não tem "$item" no inventário.');
    return false;
  }

  inventario.remove(encontrado);
  (mundo[salaAtual]!['itens'] as List<String>).add(encontrado);
  print('Você largou $encontrado no chão.');
  return true;
}

A pegadinha aqui é o as List<String> para o cast do conteúdo dinâmico do Map. Sem ele, o Dart trata o valor como dynamic e perde a verificação de tipo no .add. A variação mais comum é dar peso aos itens: largar passa a ser estratégico quando você precisa abrir espaço para algo mais valioso. Esse mecanismo aparece de novo no cap. 10, quando o inventário virar class Inventario com método largar.

▸ Desafio 5.3 - Limite de inventário com feedback

Adicione um limite de 5 itens máximo no inventário. Se estiver cheio, mostre uma mensagem clara: “Sua mochila está cheia! Você tem 5/5 itens. Largue algo antes de pegar novo item.” Use .length para verificar.

Solução de referência. Limite + feedback claro é design de UX disfarçado de código. O bug clássico é deixar o jogador “pegar” mesmo cheio e silenciosamente ignorar - ele só percebe no inventário. A solução boa rejeita antes, mostra o estado atual (5/5) e explica como sair da situação. Constante no topo do arquivo deixa o número fácil de ajustar mais tarde.

const capacidadeMaxima = 5;

bool pegarItem(String item, String salaAtual, List<String> inventario) {
  if (inventario.length >= capacidadeMaxima) {
    print('Sua mochila está cheia! '
        'Você tem ${inventario.length}/$capacidadeMaxima itens.');
    print('Largue algo antes de pegar novo item.');
    return false;
  }

  var itensSala = mundo[salaAtual]!['itens'] as List<String>;
  if (!itensSala.contains(item)) {
    print('Não há "$item" aqui.');
    return false;
  }

  itensSala.remove(item);
  inventario.add(item);
  print('Você pegou $item. '
      '(${inventario.length}/$capacidadeMaxima itens)');
  return true;
}

Note o feedback positivo no fim: depois de pegar com sucesso, o jogador vê o novo total. Isso evita a sensação de “será que pegou mesmo?” que aparece quando a mensagem é genérica. Uma variação interessante é capacidade variável por tipo de mochila - “saco simples: 3, mochila de couro: 6, mochila encantada: 10”. Aí a constante vira um campo do jogador, e o capítulo 12 (classes) tem onde encaixar isso.

▸ Desafio 5.4 - Sala de tesouro (Múltiplos itens)

Adicione uma sala especial “Câmara do Tesouro” com 5 itens valiosos (Moeda de Ouro, Anel de Prata, Diamante, Corrente, Gema). Implemente o comando "pegar tudo" que pega todos os itens da sala de uma vez, respeitando o limite do inventário. Se a mochila ficar cheia no meio, mostre quantos pôde pegar.

Solução de referência. “Pegar tudo” parece simples mas tem três comportamentos para acertar: respeitar o limite, dar feedback parcial (peguei 3 dos 5, deixei 2), e remover só o que entrou no inventário. Um for com break ao bater no limite cobre os três. Iterar sobre uma cópia da lista evita o erro clássico de mutar a coleção enquanto ela é percorrida (ConcurrentModificationError).

void pegarTudo(String salaAtual, List<String> inventario) {
  var itensSala = mundo[salaAtual]!['itens'] as List<String>;

  if (itensSala.isEmpty) {
    print('Não há nada para pegar aqui.');
    return;
  }

  var pegos = <String>[];
  var deixados = <String>[];

  // .toList() cria cópia para iterar sem corromper a original
  for (var item in itensSala.toList()) {
    if (inventario.length >= capacidadeMaxima) {
      deixados.add(item);
    } else {
      inventario.add(item);
      itensSala.remove(item);
      pegos.add(item);
    }
  }

  if (pegos.isNotEmpty) {
    print('Você pegou: ${pegos.join(", ")}');
  }
  if (deixados.isNotEmpty) {
    print('Mochila cheia. Deixou no chão: ${deixados.join(", ")}');
  }
  print('Inventário: ${inventario.length}/$capacidadeMaxima');
}

A montagem da sala em si reutiliza o padrão do desafio 5.1:

mundo['tesouro'] = {
  'nome': 'Câmara do Tesouro',
  'descricao': 'Cinco objetos brilham sobre o pedestal central.',
  'saidas': {'oeste': 'camara'},
  'itens': <String>[
    'Moeda de Ouro',
    'Anel de Prata',
    'Diamante',
    'Corrente',
    'Gema',
  ],
};

A armadilha sutil é iterar direto sobre itensSala em vez de itensSala.toList(). Como o .remove muda a lista durante a iteração, o Dart lança ConcurrentModificationError. A cópia rasa via toList() é leve e resolve. Em variações, dá para ordenar itensSala por valor antes de pegar (pega os mais caros primeiro) usando uma Map<String, int> de preços.

⚔ Boss Final 5.5 - Visualizar o mundo (Mapa de adjacência)

Crie uma função exibirMapaMundi() que imprime um diagrama ASCII mostrando todas as salas conectadas. Por exemplo, usando um formato de árvore ou de grafo simples. Use nomes de salas e setas para mostrar as conexões (Praça →[norte] Corredor, etc). Isso ajuda o jogador a visualizar a topologia do mundo.

Solução de referência. Visualizar um grafo em ASCII sem libs externas é trabalho de carpintaria: você não tenta desenhar bonito, você tenta desenhar legível. A abordagem mais simples e útil é uma lista de adjacência - cada sala vira uma linha com suas saídas. Mais elegante que tentar posicionar caixas, e mais escalável para 20+ salas. Para os jogadores que querem mapa “real”, o cap. 9 vai introduzir grids 2D.

void exibirMapaMundi() {
  print('╔═══════════════════════════════════════════════════╗');
  print('║              MAPA DO MUNDO CONHECIDO              ║');
  print('╠═══════════════════════════════════════════════════╣');

  // ordena por nome para saída estável
  var chaves = mundo.keys.toList()..sort();

  for (var chave in chaves) {
    var sala = mundo[chave]!;
    var nome = sala['nome'] as String;
    print('║ ◆ $nome');

    var saidas = sala['saidas'] as Map<String, dynamic>;
    if (saidas.isEmpty) {
      print('║    └─ (sem saídas)');
    } else {
      var entradas = saidas.entries.toList();
      for (var i = 0; i < entradas.length; i++) {
        var ultima = i == entradas.length - 1;
        var conector = ultima ? '└─' : '├─';
        var destino = mundo[entradas[i].value]!['nome'] as String;
        print('║    $conector ${entradas[i].key} → $destino');
      }
    }
    print('║');
  }

  print('╚═══════════════════════════════════════════════════╝');
}

Saída típica:

║ ◆ Biblioteca Antiga
║    └─ oeste → Praça Central
║
║ ◆ Câmara do Tesouro
║    └─ sul → Praça Central
║
║ ◆ Praça Central
║    ├─ norte → Câmara do Tesouro
║    └─ leste → Biblioteca Antiga

Os caracteres ├─ e └─ são tree-drawing Unicode (mesma família do tree no terminal). O detalhe i == entradas.length - 1 escolhe entre “branch intermediário” e “branch final”, dando o visual de árvore. Em variações, marque a sala atual com ★ ou [VOCÊ] para o jogador se orientar; descobertas progressivas (só mostrar salas visitadas) viram um filtro em cima da lista de chaves.

Capítulo 6 - Arte ASCII e StringBuffer

▸ Desafio 6.1 - Moldura com título e rodapé

Modifique a função moldura() para aceitar um parâmetro opcional rodape. Se fornecido, adicione uma linha separadora (com ─) entre o conteúdo e o rodapé, depois exiba o rodapé com alinhamento. Por exemplo: uma caixa de inventário com “Mochila Vazia” como rodapé.

Solução de referência. A moldura ganha uma área inferior opcional separada por linha horizontal. A peça importante é calcular a largura uma vez e reaproveitar: o topo, o rodapé e o separador interno usam a mesma largura, então alinhamento sai de graça. Padronizar padRight no conteúdo evita borda direita “dançando” quando linhas têm tamanhos diferentes.

void moldura(List<String> linhas, {String? rodape, int largura = 40}) {
  var topo = '╔${'═' * largura}╗';
  var meio = '╠${'═' * largura}╣';
  var base = '╚${'═' * largura}╝';

  print(topo);
  for (var linha in linhas) {
    print('║ ${linha.padRight(largura - 1)}║');
  }

  if (rodape != null) {
    print(meio);
    print('║ ${rodape.padRight(largura - 1)}║');
  }
  print(base);
}

void main() {
  moldura(
    ['Espada Curta', 'Tocha', 'Poção Pequena'],
    rodape: 'Itens: 3/5',
  );

  // mochila vazia
  moldura(
    [],
    rodape: 'Mochila Vazia',
  );
}

A armadilha clássica é misturar runes.length com string.length quando o conteúdo tem emojis ou caracteres compostos. Para texto comum em pt-BR (acentos), o length em String conta UTF-16 code units, o que coincide com “caracteres” na maioria dos casos - mas se um dia entrar 🗡️, a contagem quebra. Para o livro inteiro, ASCII e box-drawing simples são suficientes; emojis decorativos viram um caso especial só no cap. 23 (build de release).

▸ Desafio 6.2 - Barra de XP customizada

Crie uma função barraXP(int xpAtual, int xpProximoNivel, int nivel) que mostra uma barra diferente da de HP: use ▓ (preenchido) e ░ (vazio), similar à de HP mas com caracteres diferentes. Ao lado, mostre “Nível X” e a percentagem de progresso.

Solução de referência. A barra de XP segue o mesmo princípio da de HP - razão entre atual e máximo, multiplicado por uma largura fixa - mas troca os caracteres para dar identidade visual. A diferença ▓/░ versus █/▒ (HP) deixa as duas barras distinguíveis ao primeiro olhar, importante quando o HUD fica denso. Calcular a percentagem com inteiros ((xpAtual * 100 / xpProximoNivel).toInt()) evita arredondamentos confusos.

String barraXP(int xpAtual, int xpProximoNivel, int nivel, {int largura = 20}) {
  if (xpProximoNivel <= 0) return 'Nível $nivel (MAX)';

  var razao = xpAtual / xpProximoNivel;
  if (razao > 1) razao = 1;

  var preenchidas = (razao * largura).round();
  var vazias = largura - preenchidas;
  var pct = (razao * 100).toInt();

  var barra = '▓' * preenchidas + '░' * vazias;
  return 'Nível $nivel  [$barra]  $pct%  ($xpAtual/$xpProximoNivel XP)';
}

void main() {
  print(barraXP(0, 100, 1));     // 0%
  print(barraXP(45, 100, 1));    // 45%
  print(barraXP(100, 100, 1));   // 100% - prestes a subir
  print(barraXP(80, 200, 3));    // 40% no nível 3
}

Tratar xpProximoNivel <= 0 é defesa contra “nível máximo” - se o jogador chegou ao último nível, não há próximo, e dividir por zero quebraria tudo. A variação “barra que enche da direita para a esquerda” muda só a montagem da string ('░' * vazias + '▓' * preenchidas), útil para barras de tempo regressivo. Quando os capítulos avançados introduzirem cores ANSI, o mesmo código aceita um wrap '\x1B[33m' + barra + '\x1B[0m' para colorir.

▸ Desafio 6.3 - Caixa de diálogo de NPC (Com bordas especiais)

Crie uma função dialogoNPC(String nomeNPC, String fala) que exibe uma caixa estilizada: o nome do NPC em negrito (ou destacado com cores se em suporte a ANSI) no topo, a fala envolvida com uma borda especial diferente da HUD (use caracteres como ╭, ╰, │).

Solução de referência. Caixas de diálogo precisam de personalidade visual distinta da HUD para o jogador entender, em meio segundo, “isto é alguém falando”. Os arredondados ╭ ╮ ╰ ╯ no lugar de ╔ ╗ ╚ ╝ cumprem isso sem complicar. Quebrar a fala em linhas que cabem na largura disponível (usando split por espaços e contagem cumulativa) deixa diálogos longos legíveis.

List<String> quebrarTexto(String texto, int larguraMax) {
  var palavras = texto.split(' ');
  var linhas = <String>[];
  var atual = StringBuffer();

  for (var palavra in palavras) {
    if (atual.length == 0) {
      atual.write(palavra);
    } else if (atual.length + 1 + palavra.length <= larguraMax) {
      atual.write(' $palavra');
    } else {
      linhas.add(atual.toString());
      atual = StringBuffer(palavra);
    }
  }
  if (atual.length > 0) linhas.add(atual.toString());
  return linhas;
}

void dialogoNPC(String nomeNPC, String fala, {int largura = 50}) {
  var linhas = quebrarTexto(fala, largura - 4);

  print('╭${'─' * (largura - 2)}╮');
  print('│ \x1B[1m$nomeNPC\x1B[0m${' ' * (largura - 3 - nomeNPC.length)}│');
  print('├${'─' * (largura - 2)}┤');
  for (var linha in linhas) {
    print('│ ${linha.padRight(largura - 3)}│');
  }
  print('╰${'─' * (largura - 2)}╯');
}

void main() {
  dialogoNPC(
    'Velho Sábio',
    'A caverna ao norte guarda mais perigos do que ouro, aventureiro. '
    'Mas se voltar com a Chave Enferrujada, posso te mostrar um caminho oculto.',
  );
}

As sequências \x1B[1m e \x1B[0m ligam e desligam negrito em terminais que suportam ANSI; em terminais que não suportam, viram literalmente o texto - feio mas funcional. Em variações, dá para criar um enum TipoNPC { amigavel, hostil, neutro } e mudar o caractere de borda conforme o tipo (╭ para amigável, ┌ reto para hostil, ▓ para boss). Quando o cap. 12 (classes) chegar, esse padrão vira um método falar(String texto) na classe NPC, e cada subclasse customiza o visual.

▸ Desafio 6.4 - Mini-mapa do mundo

Usando StringBuffer, desenhe um mini-mapa 5x5 onde @ é o jogador, # são paredes (limites da masmorra), . é chão livre e ? são salas não visitadas. Use a sala atual e salas vizinhas para popular o mapa.

Solução de referência. Mapa 5x5 com posição central fixa para o jogador (@ no meio) e vizinhança derivada das saídas da sala atual. O StringBuffer brilha aqui porque montar a grade célula a célula com + de strings cria centenas de strings descartáveis; o StringBuffer acumula numa só. A leitura fica mais clara separando “qual caractere mostrar nesta posição” do “como imprimir”.

String desenharMiniMapa(
  String salaAtualChave,
  Set<String> visitadas,
) {
  const tamanho = 5;
  const centro = 2;

  var sala = mundo[salaAtualChave]!;
  var saidas = sala['saidas'] as Map<String, dynamic>;

  // mapeia direção -> deslocamento (linha, coluna)
  const deslocamentos = {
    'norte': [-1, 0],
    'sul':   [1, 0],
    'oeste': [0, -1],
    'leste': [0, 1],
  };

  var grade = List.generate(tamanho, (_) => List.filled(tamanho, '.'));

  // bordas
  for (var i = 0; i < tamanho; i++) {
    grade[0][i] = '#';
    grade[tamanho - 1][i] = '#';
    grade[i][0] = '#';
    grade[i][tamanho - 1] = '#';
  }

  // sala atual
  grade[centro][centro] = '@';

  // vizinhas
  for (var entry in saidas.entries) {
    var desloc = deslocamentos[entry.key];
    if (desloc == null) continue;
    var linha = centro + desloc[0];
    var col = centro + desloc[1];
    if (linha < 1 || linha >= tamanho - 1) continue;
    if (col < 1 || col >= tamanho - 1) continue;
    grade[linha][col] = visitadas.contains(entry.value) ? '.' : '?';
  }

  var sb = StringBuffer();
  for (var linha in grade) {
    sb.writeln(linha.join(' '));
  }
  return sb.toString();
}

void main() {
  var visitadas = <String>{'praca'};
  print(desenharMiniMapa('praca', visitadas));
}

Saída típica para a Praça (com saídas norte e leste, nenhuma das duas visitadas):

# # # # #
# . ? . #
# . @ ? #
# . . . #
# # # # #

A armadilha mais comum é List.filled(5, List.filled(5, '.')) - isso cria 5 referências para a mesma lista interna; mudar [0][0] muda todas as linhas. A forma correta é List.generate(5, (_) => List.filled(5, '.')), que gera cinco listas independentes. Para mapas maiores, o passo seguinte é guardar posições 2D explícitas em cada sala ('x': 3, 'y': 7) e renderizar uma janela em volta do jogador - exatamente o que o cap. 15 vai pedir.

⚔ Boss Final 6.5 - Tela de morte épica (Game Over)

Crie uma função telaGameOver(String nome, int turnos, int ouro) que monta uma tela de game over elaborada. Inclua: arte ASCII de um túmulo ou caveira, nome do herói caído, quantos turnos sobreviveu, ouro acumulado, e uma última mensagem do tipo “Descansa em paz, herói.” Use box-drawing para tornar impressionante.

Solução de referência. A tela de game over é o momento dramático do jogo - merece ser memorável. Combinar arte ASCII (caveira), painel estruturado com estatísticas e mensagem final pode ser feito tudo num único StringBuffer, mantendo o controle total da apresentação. O truque para a borda alinhada é calcular larguras com padRight/padLeft em vez de tentar contar caracteres manualmente.

String telaGameOver(String nome, int turnos, int ouro) {
  const largura = 50;

  var sb = StringBuffer();
  sb.writeln('╔${'═' * (largura - 2)}╗');
  sb.writeln('║${'GAME OVER'.padLeft((largura - 2 + 9) ~/ 2).padRight(largura - 2)}║');
  sb.writeln('╠${'═' * (largura - 2)}╣');
  sb.writeln('║${''.padRight(largura - 2)}║');

  // caveira ASCII
  const caveira = [
    '         _______',
    '        /       \\\\',
    '       |  X   X  |',
    '       |    ^    |',
    '       |  \\___/  |',
    '        \\_______/',
  ];
  for (var linha in caveira) {
    sb.writeln('║${linha.padRight(largura - 2)}║');
  }

  sb.writeln('║${''.padRight(largura - 2)}║');
  sb.writeln('║${'Aqui jaz:'.padRight(largura - 2)}║');
  sb.writeln('║${'  $nome'.padRight(largura - 2)}║');
  sb.writeln('║${''.padRight(largura - 2)}║');
  sb.writeln('║${'  Sobreviveu $turnos turnos'.padRight(largura - 2)}║');
  sb.writeln('║${'  Acumulou $ouro moedas de ouro'.padRight(largura - 2)}║');
  sb.writeln('║${''.padRight(largura - 2)}║');
  sb.writeln('╠${'═' * (largura - 2)}╣');
  sb.writeln('║${'Descansa em paz, herói.'.padLeft((largura - 2 + 23) ~/ 2).padRight(largura - 2)}║');
  sb.writeln('╚${'═' * (largura - 2)}╝');

  return sb.toString();
}

void main() {
  print(telaGameOver('Aldric, o Brando', 47, 1342));
}

A centralização via padLeft((largura + tamanho_texto) ~/ 2) é o truque clássico: você empurra o texto para a direita pela metade do espaço sobrando, depois preenche o resto à direita. Funciona melhor que tentar calcular o offset manualmente porque padRight(largura) cobre qualquer arredondamento. Em variações, adicione uma “estatística de morte” (causa: “morto por orc na Caverna do Norte”) usando a sala onde o HP zerou - aí a função vira telaGameOver(jogador, ultimaSala, ultimoInimigo). Quando o cap. 18 introduzir saves, esse mesmo formato é o que vai para o arquivo mortes.txt como obituário do herói.

Capítulo 7 - O game loop, o coração do jogo

▸ Desafio 7.1 - Eventos aleatórios (Suspense)

Adicione um evento aleatório a cada turno com 20% de probabilidade. Use import 'dart:math' e Random().nextInt(100) < 20 para decidir. Exemplos: “Você ouve passos distantes…”, “Um sopro frio passa por você”, “Algo se move na sombra”. Mostre apenas quando o evento ocorrer.

Solução de referência. Eventos atmosféricos não mudam mecânica de jogo - mudam percepção. Um susto a cada cinco turnos faz o jogador sentir que a masmorra está viva. A regra dos 20% (nextInt(100) < 20) é melhor que nextInt(5) == 0 porque, lendo o código, fica claro que é “vinte por cento”, não “um em cinco” (que dá no mesmo numericamente mas é menos imediato).

import 'dart:math';

final _rng = Random();

const atmosfericos = [
  'Você ouve passos distantes...',
  'Um sopro frio passa por você.',
  'Algo se move nas sombras à sua direita.',
  'Uma gota d\'água ecoa em algum lugar.',
  'O cheiro de enxofre fica mais forte.',
  'Você sente que está sendo observado.',
  'O chão range sob seus pés.',
];

void talvezEventoAtmosferico() {
  if (_rng.nextInt(100) < 20) {
    var msg = atmosfericos[_rng.nextInt(atmosfericos.length)];
    print('  > $msg');
  }
}

A função fica isolada e é chamada num único ponto - normalmente logo depois do jogador executar a ação do turno e antes do prompt do próximo. Isso garante que o evento parece reação ao mundo, não pré-condição. Variações fáceis: filtrar a lista por sala (mensagens de “água pingando” só fazem sentido em cavernas), usar Set para não repetir o mesmo evento duas vezes seguidas, ou aumentar a chance em salas marcadas como 'tensao': true. Cuidado com 20% sentir-se “cedo demais” - se cada mensagem custa atenção do jogador, calibrar para 10-15% costuma ser mais agradável; teste e ajuste.

▸ Desafio 7.2 - Comando examinar (Pistas escondidas)

Adicione um campo detalhes (texto longo) a cada sala além da descrição breve. O comando "examinar" ou "x" mostra esses detalhes. Serve para esconder pistas e informações extras para jogadores curiosos investigarem.

Solução de referência. Dois níveis de descrição - “olhar rápido” (entrada na sala) e “olhar atento” (comando examinar) - é o padrão clássico de aventuras de texto. A descrição breve responde “onde estou?”; o detalhe responde “o que mais tem aqui?”. Esconder pistas, números (códigos para portas trancadas), nomes de NPCs ou itens secretos no campo detalhes recompensa quem investiga sem punir quem corre.

mundo['praca'] = {
  'nome': 'Praça Central',
  'descricao': 'Uma praça empoeirada com uma fonte seca no centro.',
  'detalhes': 'Olhando com mais atenção, você nota inscrições antigas '
      'na borda da fonte: símbolos em três anéis concêntricos. '
      'Um corvo observa do telhado da capela à leste.',
  'saidas': {'norte': 'camara', 'leste': 'biblioteca'},
  'itens': <String>[],
};

void comandoExaminar(String salaAtual) {
  var sala = mundo[salaAtual]!;
  var detalhes = sala['detalhes'] as String?;
  if (detalhes == null || detalhes.isEmpty) {
    print('Você olha com atenção, mas nada chama atenção.');
    return;
  }
  print('Você olha com atenção...');
  print(detalhes);
}

// no parser do game loop:
String? parsearComando(String entrada) {
  var c = entrada.toLowerCase().trim();
  if (c == 'x' || c == 'examinar' || c == 'olhar') return 'examinar';
  // ... outros comandos
  return null;
}

A redundância “olhar / examinar / x” cobre estilos de jogador: quem prefere verbo curto, quem prefere completo, quem prefere uma tecla. Para sala sem detalhes, mostrar uma mensagem genérica é melhor que omitir - silêncio frustra. Em variações, dá para fazer detalhes condicionais: só aparece se o jogador tem tocha (sala escura), ou só na segunda visita (“agora você nota…”). A estrutura natural é um Map<String, String> em vez de uma string única, com chaves como 'sem_luz', 'com_luz', 'segunda_visita'.

▸ Desafio 7.3 - Ambiente hostil (HP dinâmico)

Cada vez que o jogador entrar numa sala com descrição contendo “escuro”, “frio”, “úmido” ou “perigoso”, perca 5 HP automaticamente. Use .contains(). Se HP chegar a 0, exiba a tela de game over. Isso torna algumas salas mais perigosas que outras: ambiente vs jogador.

Solução de referência. Dano ambiental por palavra-chave é uma forma simples de fazer o mundo “morder” sem inventar sistema de combate. O ponto delicado é dar feedback: o jogador precisa saber que perdeu HP por estar num lugar ruim, ou vai achar que o número está bugado. Mostrar uma mensagem específica (“O frio rouba sua energia (-5 HP)”) faz a mecânica ficar legível.

const palavrasPerigosas = ['escuro', 'frio', 'úmido', 'perigoso'];

int aplicarDanoAmbiental(int hpAtual, String descricaoSala) {
  var desc = descricaoSala.toLowerCase();
  var encontradas = palavrasPerigosas.where(desc.contains).toList();

  if (encontradas.isEmpty) return hpAtual;

  var dano = 5;
  var motivo = encontradas.first;
  print('O ambiente $motivo te machuca. -$dano HP.');
  return (hpAtual - dano).clamp(0, 100);
}

// usado quando o jogador entra numa sala:
void entrarNaSala(String chave, Map<String, dynamic> jogador) {
  var sala = mundo[chave]!;
  jogador['salaAtual'] = chave;
  print('== ${sala['nome']} ==');
  print(sala['descricao']);

  var hpAntes = jogador['hp'] as int;
  var hpDepois = aplicarDanoAmbiental(hpAntes, sala['descricao'] as String);
  jogador['hp'] = hpDepois;

  if (hpDepois <= 0) {
    print(telaGameOver(
      jogador['nome'] as String,
      jogador['turnos'] as int,
      jogador['ouro'] as int,
    ));
    exit(0);  // import 'dart:io'
  }
}

O clamp(0, 100) impede HP negativo - útil quando o dano vai aparecer em barras. A escolha de .contains() é genérica demais para produção: uma sala que mencione “não é perigoso” perderia HP. Para o livro, isso ainda está OK; para um jogo real, o melhor é dar a cada sala um campo 'perigos': ['frio', 'escuro'] explícito, separando narrativa de mecânica. Esse refactor aparece naturalmente quando o cap. 13 introduzir class Sala.

▸ Desafio 7.4 - Tela de estatísticas finais

Ao sair do jogo, exiba uma tabela formatada com: turnos jogados, salas visitadas (conte as únicas), itens coletados, ouro final e HP sobrevivido. Use box-drawing e formatação visual.

Solução de referência. A tela final fecha a sessão com sensação de “olha tudo o que rolou”. Mais que números, ela é o jogador revendo a própria aventura. O ingrediente sutil é o alinhamento à esquerda dos rótulos e à direita dos valores, com pontilhado entre eles - lê como uma planilha, mas elegante.

String telaEstatisticas({
  required String nome,
  required int turnos,
  required Set<String> salasVisitadas,
  required int itensColetados,
  required int ouroFinal,
  required int hpFinal,
}) {
  const largura = 50;

  String linha(String rotulo, String valor) {
    var disponivel = largura - 4 - rotulo.length - valor.length;
    if (disponivel < 3) disponivel = 3;
    var pontos = '.' * disponivel;
    return '║ $rotulo $pontos $valor ║';
  }

  var sb = StringBuffer();
  sb.writeln('╔${'═' * (largura - 2)}╗');
  sb.writeln('║${' RESUMO DA AVENTURA '.padLeft((largura + 18) ~/ 2).padRight(largura - 2)}║');
  sb.writeln('╠${'═' * (largura - 2)}╣');
  sb.writeln(linha('Herói', nome));
  sb.writeln(linha('Turnos', '$turnos'));
  sb.writeln(linha('Salas visitadas', '${salasVisitadas.length}'));
  sb.writeln(linha('Itens coletados', '$itensColetados'));
  sb.writeln(linha('Ouro acumulado', '$ouroFinal moedas'));
  sb.writeln(linha('HP final', '$hpFinal/100'));
  sb.writeln('╚${'═' * (largura - 2)}╝');
  return sb.toString();
}

void main() {
  print(telaEstatisticas(
    nome: 'Aldric',
    turnos: 38,
    salasVisitadas: {'praca', 'camara', 'biblioteca', 'tesouro'},
    itensColetados: 7,
    ouroFinal: 1342,
    hpFinal: 67,
  ));
}

Set<String> para “salas visitadas” garante que entrar duas vezes na Praça conta uma só - exatamente o que o desafio pede. Em variações, agregue mais: “Maior dano em um turno”, “NPC mais conversado”, “Item mais valioso encontrado”. Essas estatísticas mais finas saem de naturalmente quando o jogo crescer; aqui o foco é o esqueleto. Quando o cap. 18 (persistência) introduzir leaderboard, esta mesma função alimenta o arquivo de scores.

⚔ Boss Final 7.5 - Sistema de diálogo com NPC (Velho Sábio)

Adicione um NPC chamado “Velho Sábio” numa sala especial “Taverna”. O comando "falar" inicia um diálogo com 3 opções de respostas (use número ou letra). Uma das respostas revela uma dica sobre uma sala secreta. Se o jogador tiver a “Chave Enferrujada” no inventário quando resolver voltar, uma nova saída aparece na “Câmara Secreta” com ouro ou uma arma valiosa.

Solução de referência. Diálogos ramificados são o salto qualitativo do jogo: deixam de ser “navegar pelo mapa” e viram “interagir com personagens”. A estrutura mínima é (1) entrar no diálogo, (2) listar opções, (3) ler escolha, (4) executar consequência, (5) talvez voltar ao loop. O Velho Sábio também ilustra um padrão importante - estado de mundo controlado por flag: depois de ouvir a dica, uma nova rota aparece, e isso fica registrado num campo do jogador, não no mapa.

import 'dart:io';

void dialogoVelhoSabio(Map<String, dynamic> jogador, List<String> inventario) {
  print('O Velho Sábio se vira lentamente para você.');
  print('— Aventureiro, sente-se. O que você busca?');
  print('');
  print('  1) Conselhos sobre a masmorra');
  print('  2) Histórias antigas');
  print('  3) Tesouros esquecidos');
  print('  4) Sair da conversa');
  stdout.write('> ');

  var escolha = (stdin.readLineSync() ?? '').trim();

  switch (escolha) {
    case '1':
      print('— Cuide com os corredores escuros. O frio mata mais que espada.');
    case '2':
      print('— Há muito tempo, este reino era próspero...');
      print('— Mas o ouro atrai sombras. E nem todo brilho merece ser perseguido.');
    case '3':
      print('— Atrás da capela, há uma porta selada por séculos.');
      print('— Uma chave enferrujada está enterrada no jardim. '
            'Encontre-a, e o caminho se abre.');
      jogador['ouviuDicaSabio'] = true;
    case '4':
      print('— Vá com cuidado, então.');
    default:
      print('— Sua escolha não me alcança. Tente de novo.');
      return dialogoVelhoSabio(jogador, inventario);
  }
}

void talvezAbrirCamaraSecreta(
  Map<String, dynamic> jogador,
  List<String> inventario,
) {
  var ouviu = jogador['ouviuDicaSabio'] == true;
  var temChave = inventario.contains('Chave Enferrujada');
  var jaAberta = (mundo['capela']!['saidas'] as Map).containsKey('descer');

  if (ouviu && temChave && !jaAberta) {
    (mundo['capela']!['saidas'] as Map)['descer'] = 'camaraSecreta';
    mundo['camaraSecreta'] = {
      'nome': 'Câmara Secreta',
      'descricao': 'Uma sala esquecida, com cofre dourado no centro.',
      'saidas': {'subir': 'capela'},
      'itens': <String>['Espada Élfica', 'Saco de Ouro'],
    };
    print('A Chave Enferrujada brilha. Você ouve um clique vindo de baixo da capela.');
  }
}

switch com case '1': (sem break, no Dart 3+) é a forma idiomática moderna. A função recursiva return dialogoVelhoSabio(...) no default mantém o jogador no diálogo até escolher uma opção válida - alternativa: while (true) com break no fim de cada caso. A separação entre dialogoVelhoSabio (conversar) e talvezAbrirCamaraSecreta (consequência de mundo) é importante: a primeira só registra uma flag; a segunda, chamada a cada turno ou quando o jogador entra na capela, verifica as condições e abre a passagem. Esse desacoplamento facilita testar cada parte em isolado e é o gérmen do padrão Observer que vai aparecer no cap. 22.

Parte II - Sangue, Ouro e Aço

Capítulo 8 - Classes: dando vida ao jogador

▸ Desafio 8.1 - Classe Item (Objeto com peso e descrição)

Crie uma classe Item com campos nome, descricao e peso (em gramas). Substitua as strings no inventário do jogador por objetos Item. Atualize pegarItem e largarItem para usar Item em vez de String. Implemente toString() para exibir o item de forma legível (exemplo: “Espada Curta (500g)”).

Solução de referência. Transformar String em Item é o primeiro passo para dar gramática ao inventário. Em vez de “Espada Curta” como literal solto, agora temos um objeto que carrega seus próprios atributos. O ganho prático aparece nos próximos desafios: peso, descrição, comparação. Sobrescrever toString() é cortesia para depuração - print(item) mostra algo informativo em vez de Instance of 'Item'.

class Item {
  final String nome;
  final String descricao;
  final int peso;  // em gramas

  Item(this.nome, this.descricao, this.peso);

  @override
  String toString() => '$nome (${peso}g)';
}

bool pegarItem(Item item, List<Item> inventario, List<Item> itensSala) {
  if (!itensSala.contains(item)) {
    print('Não há ${item.nome} aqui.');
    return false;
  }
  itensSala.remove(item);
  inventario.add(item);
  print('Você pegou $item.');  // usa toString automaticamente
  return true;
}

void main() {
  var espada = Item('Espada Curta', 'Lâmina simples mas bem afiada.', 500);
  var tocha = Item('Tocha', 'Madeira embebida em piche.', 300);
  print(espada);  // Espada Curta (500g)
  print(tocha);   // Tocha (300g)
}

A escolha de final nos três campos é deliberada: itens não mudam de nome nem de peso depois de criados. Mais tarde, quando aparecer condição “espada quebrada” (peso muda, ou um sufixo é adicionado), o caminho idiomático é o desafio 9.5 - copyWith - em vez de mutar o item original. A armadilha comum é deixar peso como double: somar pesos com ponto flutuante gera erros de arredondamento (0.1 + 0.2 != 0.3); usar inteiro em gramas evita o problema todo.

▸ Desafio 8.2 - Peso e limite de carga

Adicione um campo pesoMaximo ao Jogador (padrão: 5000 gramas). O método pegarItem deve verificar se adicionar o novo item ultrapassaria o limite. Se ultrapassar, recuse com mensagem clara. Crie um getter pesoAtual que calcula o peso total do inventário em tempo real.

Solução de referência. Limite por peso (em vez de “número de slots”) é mais realista e dá margem para escolhas estratégicas - largar uma corrente de ferro para caber uma poção. O getter calcula sob demanda; não precisamos manter um cache porque adicionar 5-10 itens por turno e somar é trivialmente rápido. Em jogos grandes (centenas de itens), aí sim vale cache; aqui simplicidade ganha.

class Jogador {
  String nome;
  int hp;
  int ataque;
  int ouro;
  int pesoMaximo;
  final List<Item> inventario = [];

  Jogador(this.nome, {
    this.hp = 100,
    this.ataque = 5,
    this.ouro = 0,
    this.pesoMaximo = 5000,
  });

  int get pesoAtual => inventario.fold(0, (soma, item) => soma + item.peso);

  bool pegarItem(Item item) {
    if (pesoAtual + item.peso > pesoMaximo) {
      print('Pesado demais. Você carrega ${pesoAtual}g de ${pesoMaximo}g; '
            '${item.nome} pesa ${item.peso}g.');
      return false;
    }
    inventario.add(item);
    print('Você pegou $item. Carga: ${pesoAtual}g/${pesoMaximo}g.');
    return true;
  }
}

fold(0, ...) é a forma idiomática de “reduzir” uma lista a um único valor - aqui, a soma dos pesos. Para 5-20 itens, sua performance é indistinguível de um for manual, mas a leitura é mais declarativa: “fold inicia em 0 e acumula soma + item.peso”. Variação útil é dar peso negativo para “mochilas mágicas” (carregar uma mochila aumenta pesoMaximo em vez de reduzir a carga); para evitar abuso, capa pesoAtual >= 0 no getter via max(0, ...).

▸ Desafio 8.3 - Método toString robusto para Sala

Implemente toString() em Sala que mostra: nome, saídas disponíveis e quantidade de itens. Para debug, ao mudar de sala, imprima print(novaSala) para validar que o estado está correto. Formato exemplo: "Sala(Praça Central, saídas: [n, l, s], itens: 2)".

Solução de referência. toString() para Sala serve dois mestres: depuração (rastrear movimentação no log) e telemetria (registrar onde o jogador passou). O segredo é deixar o resumo compacto - você quer ver dez salas numa página, não dez parágrafos. As iniciais das direções (n, s, l, o) economizam linha sem perder informação.

class Sala {
  final String nome;
  final String descricao;
  final Map<String, String> saidas;  // direcao -> id da sala destino
  final List<Item> itens;

  Sala({
    required this.nome,
    required this.descricao,
    Map<String, String>? saidas,
    List<Item>? itens,
  })  : saidas = saidas ?? {},
        itens = itens ?? [];

  @override
  String toString() {
    var dirs = saidas.keys.map((d) => d.substring(0, 1)).join(', ');
    return 'Sala($nome, saídas: [$dirs], itens: ${itens.length})';
  }
}

void main() {
  var praca = Sala(
    nome: 'Praça Central',
    descricao: 'Praça empoeirada.',
    saidas: {'norte': 'camara', 'leste': 'biblio', 'sul': 'esgoto'},
    itens: [Item('Moeda', 'Pequena moeda de cobre.', 5)],
  );
  print(praca);  // Sala(Praça Central, saídas: [n, l, s], itens: 1)
}

O substring(0, 1) pega só a primeira letra de cada direção. Para mundos com mais de quatro direções (cima, baixo, dentro), mantenha um mapa {'norte': 'N', 'cima': 'C'} explícito para evitar colisão. Em variações de produção, é comum ter Sala.toString() formal (como acima) e um método Sala.toShortString() para casos onde só o nome importa - separar concerns evita que mudar uma quebre a outra.

▸ Desafio 8.4 - Método descrever para renderização

Adicione um método String descrever() em Sala que retorna uma descrição completa e formatada (usando StringBuffer): nome com moldura, descrição longa, saídas listadas, itens no chão com seus pesos. Substitua a função exibirSala() do Capítulo 7 por uma chamada a sala.descrever().

Solução de referência. Mover a renderização para dentro da classe (sala.descrever()) é o tipo de refactor que faz o resto do código encolher visivelmente. O main antes precisava saber montar caixa, listar saídas, listar itens; agora chama um método e pronto. Esse é o padrão Information Expert (a classe que tem os dados é a que sabe formatá-los) e aparece de novo em Jogador.ficha(), Inimigo.descrever().

class Sala {
  // ... campos do desafio 8.3 ...

  String descrever() {
    var sb = StringBuffer();
    var largura = 50;
    sb.writeln('╔${'═' * (largura - 2)}╗');
    sb.writeln('║ ${nome.padRight(largura - 3)}║');
    sb.writeln('╠${'═' * (largura - 2)}╣');
    sb.writeln('║ ${descricao.padRight(largura - 3)}║');

    if (saidas.isNotEmpty) {
      var dirs = saidas.keys.join(', ');
      sb.writeln('║ Saídas: ${dirs.padRight(largura - 11)}║');
    }

    if (itens.isNotEmpty) {
      sb.writeln('║ No chão:${''.padRight(largura - 11)}║');
      for (var item in itens) {
        sb.writeln('║   - ${item.toString().padRight(largura - 7)}║');
      }
    }

    sb.writeln('╚${'═' * (largura - 2)}╝');
    return sb.toString();
  }
}

// no game loop:
void entrarNaSala(Sala sala, Jogador jogador) {
  jogador.salaAtual = sala;
  print(sala.descrever());
}

StringBuffer em vez de concatenação de Strings não é micro-otimização aqui - é hábito que escala. Quando esta função for chamada 50+ vezes por sessão (cada movimento), criar e descartar strings pequenas custa garbage collection. StringBuffer aloca uma vez e escreve em sequência. Em variações, descrever pode receber parâmetros: sala.descrever(comDetalhes: true) para incluir detalhes longos do desafio 7.2, ou sala.descrever(ocupantes: [npc1, npc2]) para listar NPCs presentes na sala.

⚔ Boss Final 8.5 - Classe MundoTexto (Gerenciador de mundo)

Crie uma classe MundoTexto que encapsula o Map<String, Sala> e fornece métodos: Sala? obterSala(String id), void adicionarSala(Sala sala), List<String> salasConectadas(String id) que retorna as salas alcançáveis. Substitua o mapa global mundoSalas por uma instância var mundo = MundoTexto(); e use-a para todas as operações do jogo.

Solução de referência. Encapsular o Map<String, Sala> numa classe MundoTexto resolve dois problemas: (1) elimina a variável global espalhada pelo código, (2) abre porta para múltiplos mundos coexistirem (mundo principal, masmorra do sonho, mundo do tutorial). A classe vira o “departamento de geografia” do jogo. Note que salasConectadas é uma operação típica de grafos - pode crescer para BFS/DFS quando o cap. 24 introduzir pathfinding.

class MundoTexto {
  final Map<String, Sala> _salas = {};

  Sala? obterSala(String id) => _salas[id];

  void adicionarSala(String id, Sala sala) {
    if (_salas.containsKey(id)) {
      throw ArgumentError('Sala "$id" já existe no mundo.');
    }
    _salas[id] = sala;
  }

  List<String> salasConectadas(String id) {
    var sala = _salas[id];
    if (sala == null) return [];
    return sala.saidas.values.toList();
  }

  int get total => _salas.length;

  Iterable<String> get ids => _salas.keys;
}

void main() {
  var mundo = MundoTexto();
  mundo.adicionarSala('praca', Sala(
    nome: 'Praça Central',
    descricao: 'Empoeirada.',
    saidas: {'norte': 'camara'},
  ));
  mundo.adicionarSala('camara', Sala(
    nome: 'Câmara do Tesouro',
    descricao: 'Cofre dourado.',
    saidas: {'sul': 'praca'},
  ));

  print('Total: ${mundo.total} salas');
  print('Conectadas a praca: ${mundo.salasConectadas("praca")}');

  var sala = mundo.obterSala('praca');
  print(sala?.descrever() ?? 'Sala não encontrada.');
}

O _salas com underscore é privado ao arquivo - quem usa MundoTexto não consegue acessar a Map direto, só pelos métodos. Isso permite, no futuro, trocar a estrutura interna (talvez SplayTreeMap para ordenar, ou Map<String, WeakReference<Sala>> para gerência de memória) sem quebrar o resto do código. A armadilha aqui é abrir o mapa devolvendo _salas num getter público sem Map.unmodifiable(_salas) - aí a encapsulação é só fachada. Quando o capítulo 19 trouxer JSON, MundoTexto.toJson() e MundoTexto.fromJson() viram métodos naturais dessa classe.

Capítulo 9 - Construtores e encapsulamento

▸ Desafio 9.1 - Sala com API protegida

Torne os campos de Sala que são listas (itens) verdadeiramente protegidos com _: _itens. Adicione métodos públicos adicionarItem(String) e removerItem(String) em vez de expor a lista diretamente. Crie um getter List<String> get itens => List.unmodifiable(_itens) para leitura segura.

Solução de referência. O underscore (_itens) é a única marca de visibilidade no Dart - campo privado ao arquivo, não à classe. O contrato muda do “qualquer um pode mutar a lista” para “leitura é livre, escrita passa por método”. List.unmodifiable é a camada de defesa em tempo de execução: se alguém driblar e tentar sala.itens.add(...), o Dart lança UnsupportedError. Isso evita o tipo de bug em que um add perdido em outro módulo bagunça o estado do mundo.

class Sala {
  final String nome;
  final String descricao;
  final List<String> _itens;

  Sala(this.nome, this.descricao, [List<String>? itensIniciais])
      : _itens = List.of(itensIniciais ?? const []);

  List<String> get itens => List.unmodifiable(_itens);

  void adicionarItem(String item) {
    _itens.add(item);
  }

  bool removerItem(String item) {
    return _itens.remove(item);
  }
}

void main() {
  var sala = Sala('Praça', 'Empoeirada.', ['Moeda']);
  print(sala.itens);  // [Moeda]

  sala.adicionarItem('Tocha');
  print(sala.itens);  // [Moeda, Tocha]

  // Tentar mutar diretamente lança erro:
  try {
    sala.itens.add('Trapaça');
  } catch (e) {
    print('Bloqueado: $e');
  }
}

O List.of(itensIniciais ?? const []) no construtor faz uma cópia defensiva - se alguém passar uma lista e depois alterá-la externamente, a Sala continua íntegra. Sem isso, o construtor compartilharia a referência e abriria flanco para bug. A armadilha sutil é usar _itens = itensIniciais ?? [] (sem List.of), que mantém o vazamento de referência. Para coleções “pesadas” (centenas de elementos), List.unmodifiable aloca um wrapper a cada chamada do getter; nesses casos, cachear o wrapper num campo late final é o próximo passo.

▸ Desafio 9.2 - Construtores nomeados de dificuldade

Crie Jogador.facil(nome), Jogador.normal(nome) e Jogador.dificil(nome) com stats progressivamente mais altos (HP: 50/100/150, ataque: 3/5/10, ouro inicial: 0/50/200). Teste cada um imprimindo toString() e verificando se os stats fazem sentido.

Solução de referência. Construtores nomeados (Jogador.facil, Jogador.normal, etc.) são presets - o jeito idiomático de “fábrica simples” em Dart. Eles delegam ao construtor principal via : this(...), evitando duplicação. A regra é: construtor principal recebe tudo configurável; nomeados escolhem valores temáticos. Note a inversão de “dificuldade” aqui: HP mais alto em “fácil” porque o jogador aguenta mais, oposto de “fácil” significar “pouco dano causado”.

class Jogador {
  String nome;
  int hp;
  int ataque;
  int ouro;

  Jogador({
    required this.nome,
    this.hp = 100,
    this.ataque = 5,
    this.ouro = 0,
  });

  Jogador.facil(String nome)    : this(nome: nome, hp: 150, ataque: 10, ouro: 200);
  Jogador.normal(String nome)   : this(nome: nome, hp: 100, ataque: 5,  ouro: 50);
  Jogador.dificil(String nome)  : this(nome: nome, hp: 50,  ataque: 3,  ouro: 0);

  @override
  String toString() => 'Jogador($nome, HP=$hp, ATK=$ataque, ouro=$ouro)';
}

void main() {
  print(Jogador.facil('Aldric'));    // Jogador(Aldric, HP=150, ATK=10, ouro=200)
  print(Jogador.normal('Iris'));     // Jogador(Iris, HP=100, ATK=5, ouro=50)
  print(Jogador.dificil('Mariel'));  // Jogador(Mariel, HP=50, ATK=3, ouro=0)
}

A sintaxe : this(...) no construtor nomeado é a forma de chamar o construtor principal, evitando reescrever o this.hp = hp para cada nível. Se amanhã o construtor principal validar nome (if (nome.length < 2) throw...), os três presets herdam a validação automaticamente. Variações úteis: Jogador.tutorial(String nome) com HP 999 (impossível morrer), Jogador.veteran(Jogador anterior) que copia stats de um save antigo. Tudo cabe no mesmo modelo.

▸ Desafio 9.3 - Validação de movimentação

Refatore o método moverPara(String novaSalaId) para aceitar também o MundoTexto (ou Map<String, Sala>) do jogo. Valide se a sala destino realmente existe antes de permitir o movimento. Se não existir, lance uma Exception ou retorne bool false.

Solução de referência. A escolha entre throw e return false define o contrato da função. Se a entrada inválida vem do jogador (digitou direção que não existe), return false + mensagem é o jeito amigável. Se a entrada vem do código interno (algum bug tentou mover para sala fantasma), throw é melhor porque expõe o bug rápido. Aqui a função recebe input do parser, então bool faz mais sentido - e o throw fica para condição que indica corrupção real.

class Jogador {
  String nome;
  Sala? salaAtual;
  // ... outros campos ...

  Jogador(this.nome);

  bool moverPara(String direcao, MundoTexto mundo) {
    var atual = salaAtual;
    if (atual == null) {
      throw StateError('Jogador "$nome" não tem sala atual.');
    }

    var idDestino = atual.saidas[direcao];
    if (idDestino == null) {
      print('Não há saída para $direcao a partir de ${atual.nome}.');
      return false;
    }

    var destino = mundo.obterSala(idDestino);
    if (destino == null) {
      // Isso indica bug: mapa aponta para sala inexistente.
      throw StateError(
        'Sala "$idDestino" referenciada por "${atual.nome}" não existe no mundo.',
      );
    }

    salaAtual = destino;
    print('Você caminha para ${destino.nome}.');
    return true;
  }
}

A distinção - return false para “jogador errou”, throw para “mundo corrompido” - é o que separa erro esperado de bug. Para o jogador, o false permite ao loop de jogo decidir o que fazer (tentar de novo, abortar). Para o bug, o throw para o programa antes que o jogador veja estados inválidos. Variação: para playtesting, dá para trocar throw por print('BUG: ...') + return false e logar erros sem parar - mas em produção, falhar rápido protege a integridade do save.

▸ Desafio 9.4 - Construtor deArquivo resiliente (Carregamento seguro)

Aperfeiçoe o construtor Jogador.deArquivo(Map<String, dynamic> dados) com tratamento de erros: se uma chave estiver faltando ou for do tipo errado, use valores padrão em vez de crashar. Use casting seguro: (dados['hp'] as int?) ?? 100.

Solução de referência. Quando você carrega de arquivo (JSON, save, config), tudo é dynamic até prova em contrário. O as int? em vez de as int é o tique-chave: se o valor estiver presente e for int, vira int? (não-nulo); se for outra coisa (string, null, faltando), as int? retorna null, e o ?? provê o padrão. Sem isso, um save corrompido derruba o jogo na primeira linha.

class Jogador {
  String nome;
  int hp;
  int ataque;
  int ouro;

  Jogador({
    required this.nome,
    this.hp = 100,
    this.ataque = 5,
    this.ouro = 0,
  });

  Jogador.deArquivo(Map<String, dynamic> dados)
      : nome    = (dados['nome'] as String?) ?? 'Anônimo',
        hp      = (dados['hp'] as int?) ?? 100,
        ataque  = (dados['ataque'] as int?) ?? 5,
        ouro    = (dados['ouro'] as int?) ?? 0 {
    // valida ranges depois da inicialização
    if (hp < 0) hp = 0;
    if (hp > 999) hp = 999;
    if (ataque < 0) ataque = 0;
  }

  @override
  String toString() => 'Jogador($nome, HP=$hp, ATK=$ataque, ouro=$ouro)';
}

void main() {
  // save completo
  print(Jogador.deArquivo({
    'nome': 'Aldric', 'hp': 87, 'ataque': 7, 'ouro': 432,
  }));

  // save corrompido (campos faltando)
  print(Jogador.deArquivo({'nome': 'Sobrevivente'}));
  // -> Jogador(Sobrevivente, HP=100, ATK=5, ouro=0)

  // save com tipos errados (number como string)
  print(Jogador.deArquivo({
    'nome': 'Estranho', 'hp': '87',  // string em vez de int
  }));
  // -> Jogador(Estranho, HP=100, ATK=5, ouro=0)  -- hp caiu no fallback
}

A validação de ranges depois da lista de inicializadores (no corpo {...} do construtor) cobre o caso “campo presente mas absurdo” - HP de -42 ou 999999. Esse padrão é uma camada extra de defesa: o as int? valida o tipo, o if (hp < 0) valida o intervalo. Variação para produção: em vez de silenciosamente trocar valores, logue avisos (if (hp < 0) { print('WARN: hp negativo, ajustando para 0'); hp = 0; }) - útil para detectar saves corrompidos ao longo do tempo.

⚔ Boss Final 9.5 - Padrão Copy-With (Imutabilidade)

Crie ou refatore Sala para ser completamente imutável com final em todos os campos. Implemente um método Sala copyWith({List<String>? itens, bool? temLoja}) que retorna uma nova Sala com as mudanças aplicadas. Demonstre com uma sequência: sala1 → adiciona item (cria sala2) → remove item (cria sala3).

Solução de referência. copyWith é o jeito Dart/Flutter de modelar mudança em objetos imutáveis: em vez de mutar, criar uma versão nova com diferenças aplicadas. O ganho é enorme - histórico de estados grátis (cada copyWith deixa o anterior intacto), comparações por valor mais previsíveis, e thread-safety automática. Funciona bem para entidades de domínio (Sala, Jogador, Item) e mal para coisas com identidade forte (uma Conexão ao banco de dados).

class Sala {
  final String nome;
  final String descricao;
  final List<String> itens;
  final bool temLoja;

  const Sala({
    required this.nome,
    required this.descricao,
    this.itens = const [],
    this.temLoja = false,
  });

  Sala copyWith({
    String? nome,
    String? descricao,
    List<String>? itens,
    bool? temLoja,
  }) {
    return Sala(
      nome: nome ?? this.nome,
      descricao: descricao ?? this.descricao,
      itens: itens ?? this.itens,
      temLoja: temLoja ?? this.temLoja,
    );
  }

  @override
  String toString() =>
      'Sala($nome, itens: $itens, loja: $temLoja)';
}

void main() {
  var sala1 = Sala(
    nome: 'Praça',
    descricao: 'Empoeirada.',
    itens: ['Moeda'],
  );

  // sala2 = sala1 + Tocha
  var sala2 = sala1.copyWith(itens: [...sala1.itens, 'Tocha']);

  // sala3 = sala2 sem Moeda
  var sala3 = sala2.copyWith(
    itens: sala2.itens.where((i) => i != 'Moeda').toList(),
  );

  print(sala1);  // Sala(Praça, itens: [Moeda], loja: false)
  print(sala2);  // Sala(Praça, itens: [Moeda, Tocha], loja: false)
  print(sala3);  // Sala(Praça, itens: [Tocha], loja: false)
}

O detalhe nome ?? this.nome é o que faz copyWith funcionar com “passar só o que muda”: se você chama sala.copyWith(itens: [...]), todos os outros parâmetros são null e o ?? mantém o valor original. A armadilha clássica é querer “limpar” um campo opcional - copyWith(saidas: null) não funciona porque o método não distingue “não passou” de “passou null”. A solução padrão é trocar por copyWith({Sentinel saidas = Sentinel.unchanged}) ou usar a biblioteca freezed que gera tudo isso automaticamente.