Overall Architecture

• Goal: Build a web-based tool that, given a starting duel setup, uses ygopro-core + YGOpen to explore possible plays/events and outputs a graph of states and actions for visualization.
• Layers:
  • Engine wrapper (Go + CGo + YGOpen): Safe, protobuf-based interface to the duel engine.
  • Graph builder (Go): Uses the wrapper to explore state space and build graphs.
  • Web API (Go HTTP): Exposes graph generation as an HTTP API for the frontend.
  • Frontend (SPA): Visualizes graphs and allows input of setups/parameters.

1.1 High-level data flow

flowchart LR
  userBrowser[UserBrowser] --> frontendSPA[FrontendSPA]
  frontendSPA -->|HTTP/JSON| apiServer[GoWebAPI]
  apiServer -->|Go calls| graphBuilder[GraphBuilder]
  graphBuilder -->|Go calls| engineWrapper[EngineWrapper]
  engineWrapper -->|CGo calls| engineBridge[CppYGOpenCore]
  engineBridge --> ygoproCore[ygopro-core]
  engineBridge --> ygopenCodec[YGOpenCodec]

  engineWrapper -->|protobuf Duel.Msg / Answer| graphBuilder
  graphBuilder -->|Graph(nodes,edges)| apiServer
  apiServer -->|Graph JSON| frontendSPA

2. Engine Wrapper (Go + CGo + YGOpen) — Primary Focus

2.1 Objectives

• Wrap ygopro-core and YGOpen in a small, stable C API that Go can call.
• Use YGOpen protobufs as the only wire format Go needs to understand:
  • C++: raw engine messages → YGOpen::Proto::Duel::Msg → serialized bytes.
  • Go: serialized bytes → duelpb.Msg (generated from .proto).
  • Go: builds duelpb.Answer and sends serialized bytes back.
  • C++: serialized Answer → raw responses to ygopro-core.
• Encapsulate duel lifecycle, message stepping, and memory safety.

2.2 Repo layout assumptions

• Keep your existing layout and add a C++ bridge:
  • Core + C API: ygo-visualizer/bridge/ocgapi.h / .dll (already present).
  • YGOpen checkout: ygopen/ (already present in your workspace).
  • New bridge C++ files (example):
    • [ygo-visualizer]/bridge/ygopen_bridge.cpp
    • [ygo-visualizer]/bridge/ygopen_bridge.h
  • Go engine wrapper package:
    • [ygo-visualizer]/engine/engine.go
  • Generated protobuf Go types under e.g.:
    • [ygo-visualizer]/ygopenpb/duel_msg.pb.go

2.3 YGOpen / protobuf setup

• Generate Go types from YGOpen’s duel protos:
  • Source protos:
    • [ygopen]/include/ygopen/proto/duel_data.proto
    • [ygopen]/include/ygopen/proto/duel_msg.proto
    • [ygopen]/include/ygopen/proto/duel_answer.proto
  • Command (adjust paths/package):

    protoc \\
      --go_out=./ygo-visualizer/ygopenpb --go_opt=paths=source_relative \\
      ygopen/include/ygopen/proto/duel_data.proto \\
      ygopen/include/ygopen/proto/duel_msg.proto \\
      ygopen/include/ygopen/proto/duel_answer.proto

• Decide on a Go package name, e.g. ygopenpb or duelpb, and import it from wrapper and graph layers.

2.4 C++ bridge API design

Design a minimal C API that Go will call (implemented in C++, compiled into a DLL that Go links against):

• Opaque duel handle type
  • In C/C++: