Salta ai contenuti
@aws/nx-plugin
Blog

Gioco di Dungeon con IA Agentiva

Modulo 4: Implementazione dell’interfaccia utente

Sezione intitolata “Modulo 4: Implementazione dell’interfaccia utente”

Per iniziare a costruire l’interfaccia utente, vogliamo configurare il server di sviluppo locale per puntare alla sandbox distribuita. Esegui il seguente comando:

Terminal window
pnpm nx run @dungeon-adventure/game-ui:load:runtime-config

Questo comando scaricherà il file runtime-config.json distribuito e lo memorizzerà localmente nella cartella packages/game-ui/public.

Ora possiamo avviare il server di sviluppo con il seguente comando:

Terminal window
pnpm nx run @dungeon-adventure/game-ui:serve

A questo punto puoi aprire il sito locale nel browser, dove ti verrà chiesto di effettuare l’accesso e seguire le istruzioni per creare un nuovo utente. Una volta completato, dovresti vedere il sito base:

baseline-website.png

Creare una nuova route ‘/game’

Sezione intitolata “Creare una nuova route ‘/game’”

Mostriamo le capacità di @tanstack/react-router creando una nuova route type-safe. Crea semplicemente un file vuoto in questa posizione: packages/game-ui/src/routes/game/index.tsx. Noterai che il file viene aggiornato immediatamente.

Il @tanstack/react-router ha già configurato automaticamente la tua nuova route e noterai che il file appena creato è già popolato con il percorso della route:

import { createFileRoute } from '@tanstack/react-router'


export const Route = createFileRoute('/game/')({
  component: RouteComponent,
})


function RouteComponent() {
  return <div>Hello "/game/"!</div>
}

Ora, se navighi su http://localhost:4200/game, vedrai renderizzata la tua nuova pagina!

baseline-game.png

Aggiorniamo anche il file index.tsx per caricare la nuova route /game come predefinita. Nota come, quando aggiorni il campo to, hai a disposizione un elenco di route type-safe tra cui scegliere.

import { createFileRoute, Navigate } from '@tanstack/react-router';


export const Route = createFileRoute('/')({
  component: () => <Navigate to="/game" />,
});

Infine possiamo eliminare la cartella packages/game-ui/src/routes/welcome/ poiché non è più necessaria.

Aggiornamenti al layout

Sezione intitolata “Aggiornamenti al layout”

Il layout predefinito configurato è più adatto a un’applicazione aziendale in stile SaaS che a un gioco. Riconfigureremo il layout e applicheremo un tema più consono a un gioco in stile dungeon.

Apportiamo le seguenti modifiche a packages/game-ui/src:

export default {
  applicationName: 'Dungeon Adventure',
};

Ora eliminiamo il file packages/game-ui/src/hooks/useAppLayout.tsx poiché non viene utilizzato.

Integrazione dello Story Agent

Sezione intitolata “Integrazione dello Story Agent”

Successivamente creiamo un hook per inizializzare un client per interagire con il nostro Story Agent.

import { useAuth } from 'react-oidc-context';
import { useRuntimeConfig } from './useRuntimeConfig';
import { useMemo } from 'react';


export interface GenerateStoryInput {
  playerName: string;
  genre: string;
  actions: { role: string; content: string }[];
}


const generateSessionId = (playerName: string): string => {
  const targetLength = 34;
  const uuidLength = targetLength - playerName.length;


  const randomSegment = crypto
    .randomUUID()
    .replace(/-/g, '')
    .substring(0, uuidLength);


  return `${playerName}${randomSegment}`;
};


export const useStoryAgent = () => {
  const { agentArn } = useRuntimeConfig();
  const region = agentArn.split(':')[3];
  const url = `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodeURIComponent(agentArn)}/invocations?qualifier=DEFAULT`;


  const { user } = useAuth();


  return useMemo(
    () => ({
      generateStory: async function* (
        opts: GenerateStoryInput,
      ): AsyncIterableIterator<string> {
        const response = await fetch(url, {
          headers: {
            Authorization: `Bearer ${user?.id_token}`,
            'Content-Type': 'application/json',
            'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id': generateSessionId(
              opts.playerName,
            ),
          },
          method: 'POST',
          body: JSON.stringify(opts),
        });


        const reader = response.body
          ?.pipeThrough(new TextDecoderStream())
          .getReader();


        if (!reader) return;


        while (true) {
          const { value, done } = await reader.read();


          if (done) return;


          // Parse SSE format - each chunk may contain multiple events
          const lines = value.split('\n');


          for (const line of lines) {
            // SSE events start with "data: "
            if (line.startsWith('data: ')) {
              const data = line.slice(6); // Remove "data: " prefix


              try {
                const parsed = JSON.parse(data);


                // Extract text from contentBlockDelta events
                if (parsed.event?.contentBlockDelta?.delta?.text) {
                  yield parsed.event.contentBlockDelta.delta.text;
                }
                if (parsed.event?.messageStop) {
                  yield '\n';
                }
              } catch (e) {
                // Skip lines that aren't valid JSON (like Python debug output)
                continue;
              }
            }
          }
        }
      },
    }),
    [url, user?.id_token],
  );
};

Questo hook esegue le seguenti operazioni:

  • Recupera l’ARN dell’Agent da runtime-config.json
  • Costruisce l’URL di invocazione di AgentCore Runtime dall’ARN
  • Invoca l’Agent con il token JWT dell’utente autenticato e un ID sessione casuale
  • Restituisce un iteratore asincrono per consumare i chunk di messaggi streamati dall’agente

Pagine del gioco

Sezione intitolata “Pagine del gioco”

Creiamo le pagine del gioco che chiameranno le nostre API e completeranno l’implementazione del gioco. Aggiorna i seguenti file in packages/game-ui/src/routes/game:

import { FormField, Spinner } from '@cloudscape-design/components';
import { useInfiniteQuery, useMutation } from '@tanstack/react-query';
import { createFileRoute, useNavigate } from '@tanstack/react-router';
import {
  createRef,
  LegacyRef,
  MutableRefObject,
  useEffect,
  useMemo,
  useState,
} from 'react';
import { useGameApi } from '../../hooks/useGameApi';
import { IAction, IGame } from ':dungeon-adventure/game-api';


type IGameState = Omit<IGame, 'lastUpdated'> & { actions: IAction[] };


export const Route = createFileRoute('/game/')({
  component: RouteComponent,
});


// hook to check if a ref is visible on the screen
export function useIsVisible(ref: MutableRefObject<any>) {
  const [isIntersecting, setIntersecting] = useState(false);


  useEffect(() => {
    const observer = new IntersectionObserver(([entry]) =>
      setIntersecting(entry.isIntersecting),
    );


    ref.current && observer.observe(ref.current);
    return () => {
      observer.disconnect();
    };
  }, [ref]);


  return isIntersecting;
}


function RouteComponent() {
  const [playerName, setPlayerName] = useState('');
  const navigate = useNavigate();
  const ref = createRef();
  const isLastGameVisible = useIsVisible(ref);


  const gameApi = useGameApi();
  const saveGameMutation = useMutation(gameApi.games.save.mutationOptions());


  const {
    data: gamesPages,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
  } = useInfiniteQuery(
    gameApi.games.query.infiniteQueryOptions(
      { limit: 10 },
      { getNextPageParam: ({ cursor }) => cursor },
    ),
  );
  const games = useMemo(() => {
    return gamesPages?.pages.flatMap((page) => page.items) || [];
  }, [gamesPages]);


  // Fetch more games if the last game is visible and there are more games
  useEffect(() => {
    if (isLastGameVisible && hasNextPage && !isFetchingNextPage) {
      fetchNextPage();
    }
  }, [isFetchingNextPage, hasNextPage, fetchNextPage, isLastGameVisible]);


  const playerAlreadyExists = (playerName?: string) => {
    return !!games?.find((s) => s.playerName === playerName);
  };


  // create a new game
  const handleStartGame = async (
    playerName: string,
    genre: IGameState['genre'],
  ) => {
    if (playerAlreadyExists(playerName)) {
      return;
    }
    try {
      await saveGameMutation.mutateAsync({
        playerName,
        genre,
      });


      await handleLoadGame(playerName, genre);
    } catch (error) {
      console.error('Failed to start game:', error);
    }
  };


  // load an existing game
  const handleLoadGame = async (
    playerName: string,
    genre: IGameState['genre'],
  ) => {
    await navigate({
      to: '/game/$playerName',
      params: { playerName },
      search: { genre },
    });
  };


  return (
    <div className="game-interface">
      <header className="game-header">
        <h1>AI Dungeon Adventure</h1>
      </header>


      {/* New Game Section */}
      <div className="new-game">
        <h2>Start New Game</h2>
        <div className="game-setup">
          <FormField
            errorText={
              playerAlreadyExists(playerName)
                ? `${playerName} already exists`
                : undefined
            }
          >
            <input
              type="text"
              placeholder="Enter your name"
              className="name-input"
              onChange={(e) => setPlayerName(e.target.value)}
              onKeyDown={(e) => {
                if (e.key === 'Enter') {
                  const input = e.currentTarget;
                  handleStartGame(input.value, 'medieval');
                }
              }}
            />
          </FormField>
          <div className="genre-grid">
            {(['zombie', 'superhero', 'medieval'] as const).map((genre) => (
              <button
                key={genre}
                className="genre-button"
                onClick={() => {
                  const playerName = document.querySelector('input')?.value;
                  if (playerName) {
                    handleStartGame(playerName, genre);
                  }
                }}
              >
                {genre.charAt(0).toUpperCase() + genre.slice(1)}
              </button>
            ))}
          </div>
        </div>
      </div>


      {/* Saved Games Section */}
      {games && games.length > 0 && (
        <div className="saved-games">
          <h2>Continue Game</h2>
          <div className="game-list">
            {games.map((game, idx) => (
              <button
                key={game.playerName}
                ref={
                  idx === games.length - 1
                    ? (ref as LegacyRef<HTMLButtonElement>)
                    : undefined
                }
                onClick={() => handleLoadGame(game.playerName, game.genre)}
                className="game-session"
              >
                <div className="player-name">{game.playerName}</div>
                <div className="genre-name">
                  {game.genre.charAt(0).toUpperCase() + game.genre.slice(1)}
                </div>
              </button>
            ))}
            {isFetchingNextPage && <Spinner data-style="generating" size="big" />}
          </div>
        </div>
      )}
    </div>
  );
}

Dopo aver apportato queste modifiche, il server di sviluppo locale (http://localhost:4200/) dovrebbe ora avere il gioco pronto per essere giocato!

Puoi anche compilare e distribuire il codice su Cloudfront se preferisci.
game-select.png
game-conversation.png

Complimenti. Hai costruito e distribuito il tuo Gioco di Avventura Agentico nel Dungeon! 🎉🎉🎉