XFEExtension.SpaceEngineers.ScriptingHelper

using System;
using System.Collections.Generic;
using Sandbox.ModAPI.Ingame;

namespace XFEExtension.SpaceEngineers.ScriptingHelper;

/// <summary>
/// 提供一个基类，用于在基于网格的环境中编写可编程脚本，使其能够响应系统事件执行自定义逻辑。<br/>
/// Provides a base class for programmable scripts in a grid-based environment, enabling custom logic execution in
/// response to system events.
/// </summary>
/// <remarks>Inherit from ProgramBase to implement script behavior for grid systems. Override the Main method to
/// define how your script responds to arguments and update events. This class is intended for use in environments where
/// scripts are triggered by various update sources, such as timers or user actions.</remarks>
public abstract class ProgramBase : MyGridProgram
{
    /// <summary>
    /// Retrieves a block of the specified type with the given name.
    /// </summary>
    /// <typeparam name="T">The type of block to retrieve.</typeparam>
    /// <param name="name">The name of the block.</param>
    /// <returns>The block instance if found; otherwise, null.</returns>
    public T GetBlock<T>(string name) where T : class, IMyTerminalBlock
    {
        return GridTerminalSystem.GetBlockWithName(name) as T;
    }

    /// <summary>
    /// Retrieves the first block of the specified type that matches the optional filter.
    /// </summary>
    /// <typeparam name="T">The type of block to retrieve.</typeparam>
    /// <param name="collect">An optional filter function.</param>
    /// <returns>The block instance if found; otherwise, null.</returns>
    public T GetBlock<T>(Func<T, bool> collect = null) where T : class, IMyTerminalBlock
    {
        var list = new List<T>();
        GridTerminalSystem.GetBlocksOfType(list, collect);
        return list.Count > 0 ? list[0] : null;
    }

    /// <summary>
    /// Retrieves a list of blocks of the specified type, optionally filtered.
    /// </summary>
    /// <typeparam name="T">The type of blocks to retrieve.</typeparam>
    /// <param name="collect">An optional filter function.</param>
    /// <returns>A list of blocks matching the criteria.</returns>
    public List<T> GetBlocks<T>(Func<T, bool> collect = null) where T : class, IMyTerminalBlock
    {
        var list = new List<T>();
        GridTerminalSystem.GetBlocksOfType(list, collect);
        return list;
    }

    /// <summary>
    /// 当游戏内脚本执行时调用。根据传入的参数和更新源执行相应的逻辑。<br/>
    /// Executes the main entry point for the program, processing the specified argument based on the provided update
    /// source.
    /// </summary>
    /// <param name="argument">需要处理的输入字符串。不能为空；表示要处理的命令或数据。<br/>The input string to be processed. Cannot be null; represents the command or data to handle.</param>
    /// <param name="updateSource">触发执行的更新源。决定如何解释和处理参数。<br/>The source of the update triggering the execution. Determines how the argument is interpreted and processed.</param>
    public abstract void Main(string argument, UpdateType updateSource);

    /// <summary>
    /// 当游戏内脚本需要保存其状态时调用。可以在此方法中实现任何必要的逻辑来持久化数据，以便在脚本重新加载时恢复状态。<br/>
    /// Called when the program needs to save its state.
    /// </summary>
    public abstract void Save();
}