终止支持通知：2026 年 5 月 20 日， AWS 将终止对的支持。 AWS SimSpace Weaver 2026 年 5 月 20 日之后，您将无法再访问 SimSpace Weaver 控制台或 SimSpace Weaver 资源。有关更多信息，请参阅[AWS SimSpace Weaver 终止支持](https://docs.aws.amazon.com/simspaceweaver/latest/userguide/simspaceweaver-end-of-support.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 入门 SimSpace Weaver
本节提供的教程可帮助您入门 SimSpace Weaver。这些教程将向您介绍使用 SimSpace Weaver构建仿真的一般工作流程。这些教程演示了如何在中 SimSpace Weaver创建、部署和运行模拟。我们建议您从快速入门教程开始，以便在几分钟内运行模拟。之后请阅读其他教程以了解更多信息。
这些教程使用了您在[安装](setting-up_local.md)过程中下载的 SimSpace Weaver 应用程序 SDK .zip 文件中包含的示例应用程序 (`PathfindingSample`)。示例应用程序演示了所有 SimSpace Weaver 仿真共享的概念，包括空间分区、跨分区实体切换、应用程序和订阅。
在教程中，您将创建一个包含四个空间分区的模拟。`PathfindingSample` 空间应用程序的一个单独实例管理各单一分区。空间应用程序在自己的分区中创建实体。实体移动到模拟世界中的特定位置，在移动时避开障碍物。您可以使用单独的客户端应用程序（包含在 SimSpace Weaver 应用程序 SDK 中）来查看模拟。
**Topics**
+ [的快速入门教程 SimSpace Weaver](getting-started_quickstart.md)
+ [详细教程：了解构建示例应用程序的详细信息](getting-started_detailed.md)
# 的快速入门教程 SimSpace Weaver
本教程将指导您在几分钟内在 SimSpace Weaver 上完成构建和运行模拟的过程。我们建议您从本教程开始，然后再阅读[详细的教程](getting-started_detailed.md)。
**要求**
开始之前，请确保您已完成 [正在设置 SimSpace Weaver](setting-up.md) 中的步骤。
**注意**
此处提供的脚本是为了方便起见，不是必需的。有关如何手动完成这些步骤，请参阅[详细教程](getting-started_detailed.md)。
## 步骤 1：启用日志记录（可选）
**启用日志记录**
1. 导航至：
```
sdk-folder/Samples/PathfindingSample/tools
```
1. 在文本编辑器中打开架构文件：
```
pathfinding-single-worker-schema.yaml
```
1. 找到文件开头的 `simulation_properties:` 部分：
```
simulation_properties:
default_entity_index_key_type: "Vector3"
```
1. 在 `simulation_properties:` 一行之后插入以下 2 行：
```
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
```
1. 确认 `simulation_properties:` 部分与以下内容相同：
```
simulation_properties:
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
default_entity_index_key_type: "Vector3"
```
1. 保存文件并退出文本编辑器。
## 步骤 2：使用控制台客户端快速入门（选项 1）
导航至：
```
sdk-folder/Samples/PathfindingSample/tools/cloud
```
运行以下命令之一：
+ 码头工人：`python quick-start.py --consoleclient`
+ WSL：`python quick-start.py —-consoleclient --al2`
默认情况下，这将启动一个在单个工作器上使用单个分区的模拟。其他配置可以通过传递`--schema {file name}.yaml`来自`/Samples/PathfindingSample/tools/`文件夹的来启动。
**注意**
[详细教程：了解构建示例应用程序的详细信息](getting-started_detailed.md)有关此脚本功能的深入说明，请参阅。
## 第 2 步：使用虚幻引擎客户端快速入门（选项 2）
请参阅 [启动虚幻引擎视图客户端](working-with_unreal-client.md)。
## 停止并删除您的模拟
导航至：
```
sdk-folder/Samples/PathfindingSample/tools/cloud
```
查找您的模拟名称：
```
aws simspaceweaver list-simulations
```
停止并删除模拟
```
python stop-and-delete.py --simulation simulation-name
```
## 故障排除
+ **FileNotFoundError: cmake**
```
subprocess.run('cmake')
...
FileNotFoundError: The system cannot find the file specified
```
+ **解决方案：**脚本找不到命令`cmake`。请确保您安装了推荐的最低 CMake 版本，并且可以使用 PATH 中的`cmake`命令调用该版本。使用命令`cmake -version`进行验证。
+ **ImportError: 导入 libweaver\$1app\$1sdk\$1python\$1v1 时加载失败：找不到指定的模块。**
+ **解决方法：**当未使用 Python 3.9 启动 Weaver Python SDK 时，就会发生此错误。请确保与 “python” 命令关联的 python 版本为 Python 3.9。你可以通过运行`python --version`命令进行检查。
+ **启动 Docker Build 后，快速启动脚本似乎停滞不前。**
+ **解决方案：**有时 Docker 需要几分钟来预热。如果此问题持续时间超过 5 分钟，请重启 Docker 或您的系统。
+ **target\$1compile\$1features CXX 编译器 “GNU” 没有已知的功能：**
+ **解决方案：**清除 Docker 缓存，删除 weaverappbuilder Docker 镜像，删除项目构建工件，然后重新运行。`setup.py`这应该会重置你的 Docker 环境并解决错误。
# 详细教程：了解构建示例应用程序的详细信息
[快速入门教程](getting-started_quickstart.md)介绍了如何使用`quick-start.py`和构建、启动、停止和删除示例模拟`stop-and-delete.py`。本教程将详细介绍这些脚本的工作原理，以及这些脚本可以采用哪些其他参数来最大限度地提高自定义 Weaver 仿真的灵活性。
**要求**
开始之前，请确保您已完成 [正在设置 SimSpace Weaver](setting-up.md) 中的步骤。
## 步骤 1：启用日志记录（可选）
**启用日志记录**
1. 导航至：
```
sdk-folder/Samples/PathfindingSample/tools
```
1. 在文本编辑器中打开架构文件：
```
pathfinding-single-worker-schema.yaml
```
1. 找到文件开头的 `simulation_properties:` 部分：
```
simulation_properties:
default_entity_index_key_type: "Vector3"
```
1. 在 `simulation_properties:` 一行之后插入以下 2 行：
```
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
```
1. 确认 `simulation_properties:` 部分与以下内容相同：
```
simulation_properties:
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
default_entity_index_key_type: "Vector3"
```
1. 保存文件并退出文本编辑器。
## 第 2 步：开始模拟
如[快速入门教程](getting-started_quickstart.md)所示，启动示例仿真的最基本步骤是：
1. 导航至：
```
sdk-folder/Samples/PathfindingSample/tools/cloud
```
1. 运行以下命令之一：
+ **码头工人：**`python quick-start.py`
+ **WSL：**`python quick-start.py --al2`
此脚本可自动执行常见的终端命令，所有这些命令均可使用手动执行。 AWS CLI这些步骤是：
1. 将 Weaver 架构上传到 S3。
+ SimSpace Weaver 使用架构来配置您的模拟。架构是一个 YAML 格式的纯文本文件。有关更多信息，请参阅 [配置模拟](working-with_configuring-simulation.md)。
1. 构建并上传自定义容器（可选）。
+ 如果您的架构定义了自定义容器，则快速启动脚本将构建 docker 镜像并将其上传到 Amazon ECR。有关更多信息，请参阅 [自定义容器](working-with_custom-containers.md)。有关此功能的示例，请参阅`PythonBubblesSample`架构。
1. 构建项目。
+ `quick-start.py`调用中定义的`build_project`函数`build.py`。此步骤将因项目而异。对 CMake 于 PathfindingSample，使用。 CMake 和 Docker 命令可以在中找到。`build.py`
1. 将构建项目上传到 S3。
+ 您可以检查您的 S3 存储桶，确保所有上传均成功。有关使用 Amazon S3 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的[创建、配置和使用 Amazon S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html)。**
+ 示例应用程序 zip 和 S3 存储桶使用以下名称格式：
+ `weaver-sample-bucket-account-number-region`
+ 空间应用程序：`ProjectNameSpatial.zip`
+ 查看（自定义）应用程序：`ProjectNameView.zip`
1. 开始模拟。
+ 这是`aws simspaceweaver start-simulation` AWS CLI 通话的包装。有关更多信息，请参阅的[AWS CLI 命令参考](https://docs.aws.amazon.com/cli/latest/reference/simspaceweaver/) SimSpace Weaver。
+ 该脚本将循环运行，直到模拟状态变成 `STARTED` 或 `FAILED`。模拟可能需要几分钟才能启动。
1. 获取仿真详情。
+ **DescribeSimulation** API 提供有关模拟的详细信息，包括其状态。模拟可处于以下几种状态之一：
**模拟生命周期状态**
1. **`STARTING`** – 调用 **StartSimulation** 后的初始状态
1. **`STARTED`** – 所有空间应用程序均已启动且运行状况正常
1. **`STOPPING`** – 调用 **StopSimulation** 后的初始状态
1. **`STOPPED`** – 所有计算资源均已停止
1. **`DELETING`** – 调用 **DeleteSimulation** 后的初始状态
1. **`DELETED`** – 所有分配给模拟的资源均已被删除
1. **`FAILED`**— 仿真处于临界状态 error/failure 并已停止
1. **`SNAPSHOT_IN_PROGRESS`** – 正在拍摄[快照](working-with_snapshots.md)
**获取模拟详细信息**
1. 调用 **ListSimulations** API。
```
aws simspaceweaver list-simulations
```
该脚本应显示有关您的每个模拟的详细信息，类似于以下内容：
```
{
"Status": "STARTED",
"CreationTime": 1664921418.09,
"Name": "MyProjectSimulation_22-10-04_22_10_15",
"Arn": "arn:aws:simspaceweaver:us-west-2:111122223333:simulation/MyProjectSimulation_22-10-04_22_10_15",
"TargetStatus": "STARTED"
}
```
1. 调用 **DescribeSimulation** 以获取模拟详细信息。将 *simulation-name* 替换为上一步输出中模拟的 **Name**。
```
aws simspaceweaver describe-simulation --simulation simulation-name
```
该脚本应显示有关指定模拟的更多详细信息，类似于以下内容：
```
{
"Status": "STARTED",
"CreationTime": 1664921418.09,
"Name": "MyProjectSimulation_22-10-04_22_10_15",
"Arn": "arn:aws:simspaceweaver:us-west-2:111122223333:simulation/MyProjectSimulation_22-10-04_22_10_15",
"TargetStatus": "STARTED"
}
```
1. 启动定制化 App。
+ SimSpace Weaver 不管理定制化 App 的生命周期。您必须启动自定义应用程序。最佳实践是在启动模拟时钟之前启动自定义应用程序，不过，您可以在启动时钟之后启动自定义应用程序。
您可以调用 **StartApp** API 来启动您的定制化应用程序。
```
aws simspaceweaver start-app --simulation simulation-name --name app-name --domain domain-name
```
**StartApp** API 调用将使用您提供的名称创建和启动自定义应用程序的新实例。如果您提供已存在的应用程序的名称，则会收到一条错误消息。如果要重新启动特定应用程序（实例），则必须先停止该应用程序并将其删除。
**注意**
在启动自定义应用程序之前，模拟的状态必须为 `STARTED`。
示例应用程序提供了可查看模拟的 `ViewApp` 自定义应用程序。该应用程序为您提供用于连接模拟客户端的静态 IP 地址和端口号（您将在本教程后面的步骤中执行此操作）。您可以将 **domain** 看作一类具有相同可执行代码和启动选项的应用程序。**app name** 标识应用程序的实例。有关 SimSpace Weaver 概念的更多信息，请参阅[的关键概念 SimSpace Weaver](what-is_key-concepts.md)。
启动自定义应用程序后，您可以使用 **DescribeApp** API 检查其状态。
```
aws simspaceweaver describe-app --simulation simulation-name --app app-name --domain domain-name
```
**启动本教程中的查看应用程序**
1. 呼叫**StartApp**`ViewApp`。
```
aws simspaceweaver start-app --simulation simulation-name --name ViewApp --domain MyViewDomain
```
1. 调用 **DescribeApp** 以查看自定义应用程序的状态。
```
aws simspaceweaver describe-app --simulation simulation-name --app ViewApp --domain MyViewDomain
```
在自定义应用程序（实例）的状态变成 `STARTED` 后，**DescribeApp** 的输出将包括该自定义应用程序（实例）的 IP 地址和端口号。在以下示例输出中，IP 地址是 `Address` 的值，端口号是 `EndpointInfo` 数据块中 `Actual` 的值。
```
{
"Status": "STARTED",
"Domain": "MyViewDomain",
"TargetStatus": "STARTED",
"Simulation": "MyProjectSimulation_22-10-04_22_10_15",
"LaunchOverrides": {
"LaunchCommands": []
},
"EndpointInfo": {
"IngressPortMappings": [
{
"Declared": 7000,
"Actual": 4321
}
],
"Address": "198.51.100.135"
},
"Name": "ViewApp"
}
```
**注意**
`Declared` 的值是应用程序代码应绑定的端口号。的值`Actual`是向客户端 SimSpace Weaver 公开的用于连接您的应用程序的端口号。 SimSpace Weaver 将`Declared`端口映射到端`Actual`口。
**注意**
您可以使用中描述的过程[获取定制化应用程序的 IP 地址和端口号获取 IP 地址和端口号](working-with_get-ip.md)来获取任何已启动的自定义应用程序的 IP 地址和端口号。
1. 启动时钟。
+ 首次创建模拟时，它有一个时钟，但时钟不会运行。如果时钟未运行，模拟将不会更新状态。启动时钟后，它会开始向应用程序发送时钟周期。每次勾选，您的空间应用程序都会遍历它们拥有的实体，并将结果提交给 SimSpace Weaver
**注意**
启动时钟可能需要 30-60 秒。
调用 **StartClock** API。
```
aws simspaceweaver start-clock --simulation simulation-name
```
**注意**
**StartClock** API 使用您的 `simulation-name`，您可以使用 **ListSimulations** API 找到该名称：
```
aws simspaceweaver list-simulations
```
**快速启动参数**
+ -h、--help
+ 列出这些参数。
+ --干净
+ 在构建之前，请删除构建目录的内容。
+ --al2
+ 直接在本机计算机上构建，而不是 Docker。只有在 Amazon Linux 2 环境（例如 WSL）中运行时才使用此选项。
+ --仅上传
+ 仅将架构和应用程序 zip 上传到 Amazon S3，不要开始模拟。
+ --nobuild
+ 跳过重建项目。
+ --没有容器
+ 跳过重建架构中列出的模拟容器。
+ --控制台客户端
+ 自动构建并连接 config.py 中列出的控制台客户端。
+ --架构架构
+ 此调用将使用什么架构。config.py 中默认为 “架构” 的值。
+ --name NAME
+ 模拟将使用什么名字。默认为 config.py 中'项目名称'的日期-时间的值。
## 步骤 3：检查日志（可选）
SimSpace Weaver 将模拟管理消息和应用程序的控制台输出写入 Amazon CloudWatch Logs。有关使用日志的更多信息，请参阅 *Amazon Logs 用户指南中的使用日志组和 CloudWatch 日志*[流](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)。
您创建的每个模拟在 Log CloudWatch s 中都有自己的日志组。日志组的名称在模拟架构中指定。在以下架构片段中，`log_destination_service` 的值为 `logs`。这意味着 `log_destination_resource_name` 的值是日志组的名称。在本例中，日志组是 `MySimulationLogs`。
```
simulation_properties:
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
default_entity_index_key_type: "Vector3"
```
在启动模拟日志组后，您还可以使用 **DescribeSimulation** API 来查找该日志组的名称。
```
aws simspaceweaver describe-simulation --simulation simulation-name
```
以下示例显示了 **DescribeSimulation** 的输出中描述日志配置的部分。日志组的名称显示在 `LogGroupArn` 的末尾。
```
"LoggingConfiguration": {
"Destinations": [
{
"CloudWatchLogsLogGroup": {
"LogGroupArn": "arn:aws:logs:us-west-2:111122223333:log-group:MySimulationLogs"
}
}
]
},
```
每个模拟日志组都包含多个日志流：
+ **管理日志流**- SimSpace Weaver 服务生成的模拟管理消息。
```
/sim/management
```
+ **错误日志流**- SimSpace Weaver 服务生成的错误消息。只有在出现错误时，此日志流才会存在。 SimSpace Weaver 将您的应用程序写入的错误存储在它们自己的应用程序日志流中（请参阅以下日志流）。
```
/sim/errors
```
+ **空间应用程序日志流**（每个工作线程上的每个空间应用程序 1 个）– 空间应用程序生成的控制台输出。每个空间应用程序都会将日志写入其日志流。*spatial-app-id* 是 *worker-id* 末尾斜杠后的全部字符。
```
/domain/spatial-domain-name/app/worker-worker-id/spatial-app-id
```
+ **自定义应用程序日志流**（每个自定义应用程序实例 1 个）– 自定义应用程序生成的控制台输出。每个自定义应用程序实例都会将日志写入其日志流。
```
/domain/custom-domain-name/app/custom-app-name/random-id
```
+ **服务应用程序日志流**（每个服务应用程序实例 1 个）– 服务应用程序生成的控制台输出。每个服务应用程序都会将日志写入其日志流。*service-app-id* 是 *service-app-name* 末尾斜杠后的全部字符。
```
/domain/service-domain-name/app/service-app-name/service-app-id
```
**注意**
示例应用程序没有服务应用程序。
## 第 4 步：查看您的模拟
SimSpace Weaver 应用程序 SDK 提供了不同的选项来查看示例应用程序。如果你在本地不支持虚幻引擎开发，你可以使用示例控制台客户端。虚幻引擎客户端的说明假设你使用的是Windows。
当实体事件发生时，控制台客户端会显示一个事件列表。客户端从 `ViewApp` 中获取实体事件信息。如果您的控制台客户端显示了事件列表，则确认了模拟中与 `ViewApp` 和活动的网络连接。
`PathfindingSample` 模拟在二维平面上创建静止和移动的实体。移动的实体围绕静止实体移动。Unreal Engine 客户端提供实体事件的可视化效果。
### 控制台客户端
`quick-start.py`如果包含该`--consoleclient`选项，则在启动示例时可以自动构建和连接控制台客户端。要在调用后`quick-start.py`构建和连接控制台客户端，请执行以下操作：
导航至：
```
sdk-folder/Clients/TCP/CppConsoleClient
```
运行脚本来构建和连接客户端：
```
python start_client.py --host ip-address --port port-number
```
该脚本将执行以下操作：
1. 使用构建控制台客户端 CMake。
1. 使用给定的 IP 地址和端口号启动构建的可执行文件。
```
.\WeaverNngConsoleClient.exe --url tcp://ip-address:port-number
```
### 虚幻引擎客户端
请参阅[启动虚幻引擎视图客户端](working-with_unreal-client.md)。
## 第 5 步：停止并删除您的模拟
导航至：
```
sdk-folder/Samples/PathfindingSample/tools/cloud
```
查找您的模拟名称：
```
aws simspaceweaver list-simulations
```
停止并删除模拟：
```
python stop-and-delete.py --simulation simulation-name
```
该脚本`stop-and-delete.py`将执行以下操作：
1. 调用 AWS CLI 命令停止模拟。
+ `aws simspaceweaver stop-simulation`
+ 有关更多信息，请参阅的[AWS CLI 命令参考](https://docs.aws.amazon.com/cli/latest/reference/simspaceweaver/stop-simulation.html) SimSpace Weaver。
1. 调用 AWS CLI 命令删除模拟。
+ `aws simpaceweaver delete-simulation`
+ 有关更多信息，请参阅的[AWS CLI 命令参考](https://docs.aws.amazon.com/cli/latest/reference/simspaceweaver/delete-simulation.html) SimSpace Weaver。
**stop-and-delete 参数**
+ -h、--help
+ 列出这些参数。
+ --仿真模拟
+ 将模拟的名称设置为 stop-and-delete
+ --停下来
+ 只停止模拟。不会将其删除。
+ --删除
+ 仅删除模拟。只有当模拟为`STOPPED`或时才会起作用`FAILED`。
## 问题排查
参见快速[故障排除](getting-started_quickstart.md#getting-started_quickstart_troubleshooting)入门教程。