Anchor Yard

⚓ anchor-yard is a simple and effective performance profiling and world snapshot tool for the shipyard ECS.

It helps you identify slow systems and capture the world state at the time of execution, making it easy to debug and analyze bottlenecks.

🤔 What Problem Does It Solve?

When developing complex games or simulations with shipyard, it can be difficult to figure out why a particular system is slowing down. anchor-yard solves this problem by:

Automatic Snapshots: Automatically saves a snapshot of the World state when a system's execution time exceeds a set threshold.
State Analysis: Load saved snapshots to precisely analyze all entity and component data at the moment a performance drop occurred.
Minimal Code Changes: Apply profiling and snapshot capabilities to your existing systems with a single #[snapshot_system] attribute.

✨ Key Features

Threshold-based Snapshots: Automatically captures a snapshot of systems that exceed a specified execution time in milliseconds.
Easy Integration: Simply add the #[snapshot_system] attribute to your system functions.
Save and Restore World State: Save the entire state of the World to a file and restore it perfectly later.
Flexible Configuration: Selectively register which components to include in the snapshot.

🚀 Getting Started

1. Add Dependency

Add anchor-yard to your Cargo.toml file.

[dependencies]

anchor-yard = "0.1.0" # Use your desired version

shipyard = "0.6"

serde = { version = "1.0", features = ["derive"] }

2. Register Components

At your application's entry point (e.g., in the main function), register the components you want to include in snapshots.

use anchor_yard::REGISTRY;
use shipyard::{Component, World};
use serde::{Serialize, Deserialize};

#[derive(Component, Serialize, Deserialize)]
struct Position { x: f32, y: f32 }

#[derive(Component, Serialize, Deserialize)]
struct Velocity { x: f32, y: f32 }

fn main() {
    let mut registry = REGISTRY.lock().unwrap();
    registry.register::<Position>();
    registry.register::<Velocity>();
}

3. Apply Attribute to System

Add the #[snapshot_system] attribute to the system you want to profile. You can set threshold_ms to specify the execution time that triggers a snapshot.

use anchor_yard::snapshot_system;
use shipyard::{View, ViewMut};

#[snapshot_system(threshold_ms = 10)] // Creates a snapshot if it takes longer than 10ms
fn slow_combat_system(mut healths: ViewMut<Health>, positions: View<Position>) {
    // ... system logic ...
    std::thread::sleep(std::time::Duration::from_millis(15));
}

4. Run the World

When running your system, use run_with_snapshot or run_workload_with_snapshot.

use anchor_yard::WorldSnapshotExt;

let mut world = World::new();
// ... add entities and components ...

// Run an individual system
world.run_with_snapshot(|| world.run(slow_combat_system));

// Run a workload
world.add_workload("game_loop", slow_combat_system);
world.run_workload_with_snapshot("game_loop").unwrap();

Now, if slow_combat_system takes longer than 10ms to execute, a slow_combat_system_TIMESTAMP.snapshot file will be created in the snapshots/ directory!

📦 Crate Structure

anchor-yard follows a modular design:

anchor-yard: The main crate that integrates all features for the easiest use.
anchor-yard-core: Contains the core logic for creating, saving, and restoring snapshots.
anchor-yard-macros: Provides the #[snapshot_system] procedural macro.

Anchor Yard (Korean)

⚓ anchor-yard는 shipyard ECS를 위한 간단하고 효과적인 성능 프로파일링 및 월드 스냅샷 도구입니다.

느린 시스템을 식별하고, 실행 시점의 월드 상태를 캡처하여 병목 현상을 쉽게 디버깅하고 분석할 수 있도록 도와줍니다.

🤔 무엇을 해결하나요?

shipyard를 사용하여 복잡한 게임이나 시뮬레이션을 개발할 때, 특정 시스템이 왜 느려지는지 파악하기 어려울 수 있습니다. anchor-yard는 이 문제를 다음과 같이 해결합니다:

자동 스냅샷: 시스템 실행 시간이 설정된 임계값을 초과하면 자동으로 해당 시점의 World 상태를 스냅샷으로 저장합니다.
상태 분석: 저장된 스냅샷을 로드하여, 성능 저하가 발생했을 때의 모든 엔티티와 컴포넌트 데이터를 정밀하게 분석할 수 있습니다.
최소한의 코드 변경: 간단한 #[snapshot_system] 어트리뷰트 하나로 기존 시스템에 프로파일링 및 스냅샷 기능을 적용할 수 있습니다.

✨ 주요 기능

임계값 기반 스냅샷: 지정한 시간(ms)을 초과하는 시스템의 스냅샷을 자동으로 캡처합니다.
간편한 통합: #[snapshot_system] 어트리뷰트를 시스템 함수에 추가하기만 하면 됩니다.
월드 상태 저장 및 복원: World의 전체 상태를 파일로 저장하고, 나중에 다시 로드하여 완벽하게 복원할 수 있습니다.
유연한 설정: 어떤 컴포넌트를 스냅샷에 포함할지 선택적으로 등록할 수 있습니다.

🚀 시작하기

1. 의존성 추가

Cargo.toml 파일에 anchor-yard를 추가합니다.

[dependencies]

anchor-yard = "0.1.0" # 원하는 버전을 사용하세요

shipyard = "0.6"

serde = { version = "1.0", features = ["derive"] }

2. 컴포넌트 등록

애플리케이션 시작 지점 (예: main 함수)에서 스냅샷에 포함할 컴포넌트들을 등록합니다.

use anchor_yard::REGISTRY;
use shipyard::{Component, World};
use serde::{Serialize, Deserialize};

#[derive(Component, Serialize, Deserialize)]
struct Position { x: f32, y: f32 }

#[derive(Component, Serialize, Deserialize)]
struct Velocity { x: f32, y: f32 }

fn main() {
    let mut registry = REGISTRY.lock().unwrap();
    registry.register::<Position>();
    registry.register::<Velocity>();
}

3. 시스템에 어트리뷰트 적용

프로파일링하고 싶은 시스템에 #[snapshot_system] 어트리뷰트를 추가합니다. threshold_ms를 설정하여 스냅샷을 트리거할 실행 시간을 지정할 수 있습니다.

use anchor_yard::snapshot_system;
use shipyard::{View, ViewMut};

#[snapshot_system(threshold_ms = 10)] // 10ms 이상 걸리면 스냅샷 생성
fn slow_combat_system(mut healths: ViewMut<Health>, positions: View<Position>) {
    // ... 시스템 로직 ...
    std::thread::sleep(std::time::Duration::from_millis(15));
}

4. 월드 실행

시스템을 실행할 때 run_with_snapshot 또는 run_workload_with_snapshot을 사용합니다.

use anchor_yard::WorldSnapshotExt;

let mut world = World::new();
// ... 엔티티와 컴포넌트 추가 ...

// 개별 시스템 실행
world.run_with_snapshot(|| world.run(slow_combat_system));

// 워크로드 실행
world.add_workload("game_loop", slow_combat_system);
world.run_workload_with_snapshot("game_loop").unwrap();

이제 slow_combat_system이 10ms 이상 실행되면 snapshots/ 디렉토리에 slow_combat_system_TIMESTAMP.snapshot 파일이 생성됩니다!

📦 크레이트 구조

anchor-yard는 모듈식 설계를 따릅니다:

anchor-yard: 핵심 기능을 통합하고 가장 쉽게 사용할 수 있는 메인 크레이트입니다.
anchor-yard-core: 스냅샷 생성, 저장, 복원 등 핵심 로직을 포함합니다.
anchor-yard-macros: #[snapshot_system] 절차적 매크로를 제공합니다.

anchor-yard 0.1.3