終止支援通知： 將於 2026 AWS 年 5 月 20 日結束對 的支援 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. 在行 後面插入以下 2 行`simulation_properties:`：
```
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
```
請執行下列其中一個命令：
+ Docker： `python quick-start.py --consoleclient`
+ WSL： `python quick-start.py —-consoleclient --al2`
根據預設，這將在單一工作者上啟動具有單一分割區的模擬。其他組態可以透過`--schema {file name}.yaml`從 `/Samples/PathfindingSample/tools/` 資料夾傳遞 來啟動。
**注意**
[詳細教學課程：了解建置範例應用程式時的詳細資訊](getting-started_detailed.md) 如需此指令碼功能的深入說明，請參閱 。
## 步驟 2：使用 Unreal Engine 用戶端快速入門 （選項 2)
請參閱 [啟動 Unreal Engine 檢視用戶端](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 時 DLL 載入失敗：找不到指定的模組。 **
+ **解決方案：**當 Python 3.9 未用於啟動 Weaver Python SDK 時，會發生此錯誤。請確保與「python」命令相關聯的 Python 版本為 Python 3.9。您可以執行 `python --version`命令來檢查 。
+ **快速入門指令碼在啟動 Docker Build 後卡在 。**
+ **解決方法：**有時候 Docker 需要幾分鐘的時間來暖機。如果此問題持續超過 \$15 分鐘，請重新啟動 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. 在行 後面插入以下 2 行`simulation_properties:`：
```
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. 執行其中一個模糊命令：
+ **Docker：** `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`。此步驟會根據專案而有所不同。對於 PathfindingSample，會使用 CMake。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`** – 模擬發生嚴重錯誤/失敗並停止
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. 啟動自訂應用程式。
+ SimSpace Weaver 不會管理自訂應用程式的生命週期。您必須啟動自訂應用程式。最佳實務是在啟動模擬時鐘之前啟動自訂應用程式，但您可以在啟動時鐘之後啟動自訂應用程式。
您可以呼叫 **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 公開以連接到您 app 的連接埠號碼。將`Declared`連接埠 SimSpace Weaver 映射至`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、 -求助
+ 列出這些參數。
+ --clean
+ 在建置之前刪除建置目錄的內容。
+ --al2
+ 直接在原生機器而非 Docker 上建置。只有在 Amazon Linux 2 環境中執行 ，例如 WSL 時，才能使用此功能。
+ --uploadonly
+ 僅將結構描述和應用程式 zip 上傳至 Amazon S3，請勿啟動模擬。
+ --nobuild
+ 略過重建專案。
+ --無容器
+ 略過重建結構描述中列出的模擬容器。
+ --consoleclient
+ 自動建置並連接 https：//config.py 中列出的主控台用戶端。
+ --結構描述 SCHEMA
+ 此調用將使用的結構描述。預設為 config.py 中的 'SCHEMA' 值。
+ --name NAME
+ 模擬的名稱。預設為 config.py 中 'PROJECT\$1NAME'-date-time 的值。
## 步驟 3：檢查日誌 （選用）
SimSpace Weaver 會將模擬管理訊息和主控台輸出從應用程式寫入 Amazon CloudWatch Logs。如需使用日誌的詳細資訊，請參閱《*Amazon CloudWatch Logs 使用者指南*》中的[使用日誌群組和日誌串流](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)。
您建立的每個模擬在 CloudWatch Logs 中都有自己的日誌群組。日誌群組的名稱是在模擬結構描述中指定。在下列結構描述程式碼片段中， 的值`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 應用程式開發套件提供檢視範例應用程式的不同選項。如果您沒有 Unreal Engine 開發的任何本機支援，您可以使用範例主控台用戶端。Unreal Engine 用戶端的指示假設您使用 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
```
### Unreal Engine 用戶端
請參閱 [啟動 Unreal Engine 檢視用戶端](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、 -求助
+ 列出這些參數。
+ --simulation SIMULATION
+ 要stop-and-delete的模擬名稱
+ --stop
+ 僅停止模擬。不會刪除它。
+ --刪除
+ 僅刪除模擬。只有在模擬為 `STOPPED`或 時，才會運作`FAILED`。
## 疑難排解
請參閱快速入門教學[故障診斷](getting-started_quickstart.md#getting-started_quickstart_troubleshooting)中的 。