WebGAL Terre 貢献ガイド

WebGAL Terre への貢献を歓迎します！WebGAL Terre は、私たちが最も創造性と競争力を注ぎ込むプロジェクトです。プログラミングに不慣れなクリエイターが WebGAL を使って作品を制作できるように支援することに力を注いでいます。ゲームスクリプトからカスタム UI まで、ほぼすべての制作関連タスクにおいて、敷居を下げ、制作をより簡単にすべく、グラフィカルな編集方法を提供することに努めています。

それに加えて、ほぼすべての機能に対してコードによる記述方法も提供しています。コード編集とグラフィカル編集モジュールは完全に互換性を持つように設計されているため、クリエイターは 2 つのモードをシームレスに切り替えることができます。

このエキサイティングなプロジェクトに参加する前に、以下の規約をお読みください。

貢献の要件

AI の使用について

AI はソフトウェア開発の方法を大きく変え、ソフトウェア開発の効率を大幅に向上させると同時に、多くの課題ももたらしました。UI の作成において、AI を使って広範囲に UI を作成すると「AI Slop」と呼ばれる問題が極めて発生しやすくなります。AI が作成した UI は人間の使用習慣に合致しないことが多く、時には無意味な説明テキストが含まれたり、レイアウト面でもオーバーフローやズレなどの問題が頻繁に発生します。また、AI がコードを作成する際、エラーを素早く修正するために大量の冗長なコードや「防御的プログラミング」コードを記述してしまいがちです。AI にとって、より簡潔で、読みやすく保守しやすいコードを作成することは依然として困難です。

WebGAL プロジェクトでは、AI の使用に関して以下の規約を定めています。コードを記述する際は、これらの規約を遵守してください。

人間がアーキテクチャと実装方針を設計し、AI が記述する。AI に直接目標を指示するだけで人間が設計に関与しないコーディング方法は受け入れられません。AI がコードを作成した後は、人間がコードをレビューし、関連モジュールをテストした上でなければ、PR を提出することはできません。
Issue や PR の本文に AI で生成されたテキストを使用することは禁止します。詳細でなくても構いませんので、問題を特定できる、または自身の意図を説明できる十分な情報を記載してください。詳細すぎる AI 生成の説明は、かえって要点を把握しづらくし、真に重要な情報への集中を妨げてしまいます。
UI については、人間がプロトタイプ設計を行う必要があり、AI は実装にのみ使用できます。過去の複数のバージョン反復の経験から、AI が機能に基づいて直接生成した UI は、期待を大幅に下回るものであると判断されています。

貢献内容をより良く理解し、レビューするために、以下の点にご注意ください。

コードコメント: コードのロジックを理解しやすくするために、重要な部分にコメントを追加することをお勧めします。
機能テスト: 機能を追加または変更した場合、機能が正しく動作することを確認するためのテスト方法を提供してください。コードのリファクタリングを行った場合は、影響を受ける範囲をカバーし、リファクタリングによって新しい問題が発生していないことを確認するためのテスト方法も提供してください。
明確な説明: プルリクエストを提出する際には、行った変更と、その背後にある理由を簡単に説明してください。これは、貢献内容をより早く理解するのに役立ちます。

プロジェクト紹介

WebGAL Terre は、TypeScript を使用したフルスタック開発で、パッケージマネージャーとして yarn を、monorepo マネージャーとして yarn workspace を使用しています。

プロジェクトの起動

依存関係のインストール

まず、Yarnopen in new window がインストールされていることを確認してください。Yarn がインストールされていない場合は、公式ドキュメントに従ってインストールしてください。

リポジトリのクローン

WebGAL Terre のリポジトリは WebGAL Terre - GitHubopen in new window にあります。

依存関係のインストール

yarn

開発サーバーの起動

yarn dev

これにより、開発サーバーが起動し、デフォルトブラウザでアプリケーションが開きます。

プロジェクトのビルド

リリース可能なバージョンを生成するには、ビルドスクリプトを実行する必要があります。

Windows: release.sh
その他の環境: プロジェクトのルートディレクトリにある対応するビルドスクリプトを確認してください。

ビルドが完了すると、release ディレクトリにビルド成果物が配置されます。

Terre に同梱されている WebGAL エンジンテンプレートの更新

通常、WebGAL の更新後、最新バージョンのエンジンテンプレートを Terre プロジェクトに更新します。Terre でカスタマイズした WebGAL エンジンを使用する場合は、次の手順に従ってください。

WebGAL エンジンリポジトリをクローンします（隣接ディレクトリにクローンすることをお勧めします。これにより、自動化スクリプトを使用できます）

git clone https://github.com/OpenWebGAL/WebGAL.git

（Terre プロジェクトの隣接ディレクトリに WebGAL プロジェクトをクローンした場合、そうでない開発者は無視してください） WebGAL エンジンリポジトリで自動化スクリプトを実行して、WebGAL を WebGAL Terre にビルドします

sh release-to-terre.sh

注意

以下の手順は、手動でビルドして Terre のエンジンテンプレートを更新する場合に適用されます。自動化スクリプトを使用する開発者は無視してください！

WebGAL プロジェクトをビルドします（この手順は WebGAL エンジンリポジトリで実行します）

yarn
yarn build

WebGAL Terre のエンジンテンプレートを削除し、エンジンプロジェクトのビルド成果物を WebGAL Terre のテンプレートディレクトリに移動します

ここでは、Terre プロジェクトの隣接ディレクトリに WebGAL プロジェクトをクローンしていると想定しています。異なるディレクトリ構造を使用している場合は、それに応じて変更してください。

# Terre ディレクトリに移動します
cd ../WebGAL_Terre/packages/terre2/assets/templates/WebGAL_Template || exit
# 他のファイルを削除します
rm -r assets
rm -r index.html
rm -r webgal-serviceworker.js

# WebGAL ビルドディレクトリに移動します
cd ../../../../../../WebGAL/packages/webgal || exit
# コピーします
cp -r dist/index.html ../../../WebGAL_Terre/packages/terre2/assets/templates/WebGAL_Template
cp -r dist/assets ../../../WebGAL_Terre/packages/terre2/assets/templates/WebGAL_Template
cp -r dist/webgal-serviceworker.js ../../../WebGAL_Terre/packages/terre2/assets/templates/WebGAL_Template

パッケージ紹介

パッケージ名	説明
`packages/dev-server`	80ポートでデバッグ、サーバーユーザーに便利
`packages/origine2`	エディターフロントエンド
`packages/terre-electron`	Electron 版 Terre エディター
`packages/terre2`	エディターバックエンド
`packages/vscode-ws-jsonrpc-webgal`	WebGAL エディターバックエンド用のカスタムパッケージ、いくつかのバグを修正
`packages/WebGAL-electron`	WebGAL の Electron パッケージ

WebGAL Terre フロントエンドとバックエンドの連携デバッグガイド

WebGAL Terre は、TypeScript を使用したフルスタックプロジェクトであり、OpenAPI を使用してバックエンドインターフェースをリクエストするためのコードを生成します。

このプロセスを正しく機能させるには、WebGAL Terre バックエンドのインターフェースを開発する際に、以下のアノテーションに注意してください。

1. インターフェースアノテーションの紹介

次のコード例は、バックエンドインターフェースに必要な主要なアノテーションを示しています。

@Post('createGame')
  @ApiOperation({ summary: 'Create a new game' })
  @ApiResponse({ status: 200, description: 'Game creation result.' })
  @ApiBody({ type: CreateGameDto, description: 'Game creation data' })
  async createGame(@Body() createGameData: CreateGameDto) {
    const createResult = await this.manageGame.createGame(
      createGameData.gameName,
      createGameData.derivative,
      createGameData.templateName,
    );
    if (createResult) {
      return { status: 'success' };
    } else {
      return { status: 'failed' }; 
    }
  }

2. コード例の詳細説明

各アノテーションの役割を理解するために、このコードを 1 行ずつ分析してみましょう。

@Post('createGame'):
- @Post: これが POST リクエストインターフェースであることを示します。
- 'createGame': インターフェースのパス、つまり /createGame を定義します。
@ApiOperation({ summary: 'Create a new game' }):
- @ApiOperation: インターフェースの機能を記述するために使用されます。
- summary: インターフェースの役割を簡単に要約し、生成された OpenAPI ドキュメントに表示されます。
@ApiResponse({ status: 200, description: 'Game creation result.' }):
- @ApiResponse: インターフェースの可能な応答を記述します。
- status: HTTP ステータスコードを指定します。ここでは 200 で、成功を示します。
- description: このステータスコードでの応答内容を記述します。
@ApiBody({ type: CreateGameDto, description: 'Game creation data' }):
- @ApiBody: リクエスト本文のデータ型と説明を指定します。
- type: リクエスト本文のデータ構造を示します。ここでは、事前に定義された DTO（データ転送オブジェクト）である CreateGameDto を使用しています。
- description: リクエスト本文データの意味を記述します。
async createGame(@Body() createGameData: CreateGameDto):
- async: これが非同期関数であることを示します。
- createGame: インターフェースの関数名です。
- @Body(): リクエスト本文からデータを取得します。
- createGameData: CreateGameDto: リクエスト本文データを CreateGameDto 型のオブジェクトに解析します。

3. フロントエンドプロジェクトでの OpenAPI の更新

フロントエンドプロジェクトで最新のバックエンドインターフェースを使用できるようにするには、開発中に OpenAPI 定義を定期的に更新する必要があります。

手順:

バックエンドプロジェクトが実行されていることを確認します（前述のように、yarn dev を実行します）。
packages/origine2 ディレクトリで、コマンド yarn openapi を実行します。

このコマンドは、バックエンドコードのアノテーションに基づいて最新の OpenAPI 定義ファイルを自動的に生成します。フロントエンドプロジェクトは、このファイルを使用してインターフェースをリクエストするためのコードを生成し、フロントエンドとバックエンドのインターフェースの一貫性を保証します。

4. フロントエンドプロジェクトでのインターフェースの使用

WebGAL フロントエンドプロジェクトでは、次の方法でバックエンドインターフェースを呼び出すことができます。

api オブジェクトをインポートします: import {api} from "@/api";
api オブジェクトのメソッドを呼び出します。例: api.manageGameControllerGetGameList()。

api オブジェクトには、すべてのバックエンドインターフェースに対応するメソッドが含まれており、インターフェース名に基づいて直接呼び出すことができます。

開発に関するその他の情報

これに加えて、ソースコードの重要なディレクトリには、このモジュールの原理を説明するドキュメントもいくつか用意されています。この情報は中国語で提供されます。今日では、大規模言語モデルは翻訳において十分な性能を発揮するため、中国語が読めなくても心配する必要はありません。大規模言語モデルを使用して、自分の言語に翻訳してみてください。

WebGAL Terre 貢献ガイド

# WebGAL Terre 貢献ガイド

# 貢献の要件

# AI の使用について

# プロジェクト紹介

# プロジェクトの起動

# 依存関係のインストール

# リポジトリのクローン

# 依存関係のインストール

# 開発サーバーの起動

# プロジェクトのビルド

# Terre に同梱されている WebGAL エンジンテンプレートの更新

# パッケージ紹介

# WebGAL Terre フロントエンドとバックエンドの連携デバッグガイド

# 開発に関するその他の情報

WebGAL Terre 貢献ガイド

貢献の要件

AI の使用について

プロジェクト紹介

プロジェクトの起動

依存関係のインストール

リポジトリのクローン

依存関係のインストール

開発サーバーの起動

プロジェクトのビルド

Terre に同梱されている WebGAL エンジンテンプレートの更新

パッケージ紹介

WebGAL Terre フロントエンドとバックエンドの連携デバッグガイド

開発に関するその他の情報