跳转到内容
@aws/nx-plugin
Blog

代理式AI地牢游戏

模块四：用户界面实现

Section titled “模块四：用户界面实现”

要开始构建用户界面，我们需要将本地开发服务器配置指向已部署的沙盒环境。运行以下命令：

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

该命令将拉取已部署的 runtime-config.json 文件，并存储在本地 packages/game-ui/public 目录中。

现在可以通过以下命令启动开发服务器：

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

随后在浏览器中打开本地网站，系统将提示登录并创建新用户。完成后您将看到基础网站界面：

baseline-website.png

创建新路由 ‘/game’

Section titled “创建新路由 ‘/game’”

我们将通过创建类型安全路由来展示 @tanstack/react-router 的功能。在指定位置创建空文件：packages/game-ui/src/routes/game/index.tsx。您会注意到文件立即被更新。

@tanstack/react-router 已自动配置新路由，新建文件将包含以下路径定义：

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


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


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

访问 http://localhost:4200/game 即可查看新页面：

baseline-game.png

更新 index.tsx 文件以默认加载新路由。注意修改 to 字段时，系统会提供类型安全的路由选项。

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


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

最后可删除不再需要的 packages/game-ui/src/routes/welcome/ 目录。

布局更新

Section titled “布局更新”

默认布局更适用于SaaS类商业应用。我们将重新配置布局和主题，使其符合地牢游戏风格。修改以下文件：

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

删除未使用的 packages/game-ui/src/hooks/useAppLayout.tsx 文件。

故事代理集成

Section titled “故事代理集成”

创建用于初始化故事代理客户端的钩子：

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],
  );
};

该钩子实现以下功能：

  • 从 runtime-config.json 获取代理ARN
  • 根据ARN构建代理运行时调用URL
  • 使用用户JWT令牌和随机会话ID调用代理
  • 返回异步迭代器用于处理流式消息

游戏页面

Section titled “游戏页面”

创建调用API的最终游戏页面。更新以下文件：

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>
  );
}

完成修改后，本地开发服务器（http://localhost:4200/）即可运行完整游戏！

您也可以选择构建并部署至Cloudfront
game-select.png
game-conversation.png

恭喜！您已成功构建并部署智能地牢冒险游戏！🎉🎉🎉