defmodule Ecspanse do
  @moduledoc """
  Ecspanse is an Entity Component System (ECS) framework for Elixir.

  > #### Note {: .info}
  > Ecspanse is not a game engine, but a flexible foundation
  > for managing state and building logic, offering features like:
  > - flexible queries with multiple filters
  > - dynamic bidirectional relationships
  > - versatile tagging capabilities
  > - system event subscriptions
  > - asynchronous system execution

  The core structure of the Ecspanse library is:

  - `Ecspanse`: The main module used to configure and interact with the library.
  - `Ecspanse.Server`: The server orchestrates the execution of systems and the storage of components, resources, and events.
  - `Ecspanse.Entity`: A simple struct with an ID, serving as a holder for components.
  - `Ecspanse.Component`: A struct that may hold state information or act as a simple label for an entity.
  - `Ecspanse.System`: Holds the application core logic. Systems run every frame, either synchronously or asynchronously.
  - `Ecspanse.Resource`: Global state storage, similar to components but not tied to a specific entity. Resources can only be created, updated, and deleted by synchronously executed systems.
  - `Ecspanse.Query`: A tool for retrieving entities, components, or resources.
  - `Ecspanse.Command`: A mechanism for changing components and resources state. They can only be triggered from a system.
  - `Ecspanse.Event`: A mechanism for triggering events, which can be listened to by systems. It is the way to communicate externally with the systems.

  ## Usage

  To use Ecspanse, a module needs to be created, invoking `use Ecspanse`. This implements the `Ecspanse` behaviour, so the `setup/1` callback must be defined. All the systems and their execution order are defined in the `setup/1` callback.

  ## Examples

  ```elixir
  defmodule TestServer1 do
    use Ecspanse, fps_limit: 60, version: 1

    def setup(data) do
      data
      |> add_startup_system(Demo.Systems.SpawnHero)
      |> add_frame_start_system(Demo.Systems.PurchaseItem)
      |> add_system(Demo.Systems.MoveHero)
      |> add_frame_end_system(Ecspanse.System.Timer)
      |> add_shutdown_system(Demo.Systems.Cleanup)
    end
  end
  ```

  > #### Info  {: .info}
  > The `Ecspanse` system scheduling functions are imported by default
  > for the setup module that `use Ecspanse`

  ## Configuration

  The following configuration options are available:
  - `:fps_limit` (optional) - integer or :unlimited - the maximum number of frames per second. Defaults to :unlimited.
  - `:version` (optional) - non negative integer - the version of the ECS game logic.
  Can be used to determine backwards compatibility when saving and loading state(see `Ecspanse.Snapshot` for details).
  Defaults to 0.


  # Special Resources

  Some special resources, such as `FPS`, are created by default by the framework.

  """

  alias __MODULE__
  alias Ecspanse.Util

  require Logger

  defmodule Data do
    @moduledoc """
    The `Data` module defines a struct that holds the state of the Ecspanse initialization process.
    This struct is passed to the `setup/1` callback, which is used to define the running systems.
    After the initialization process the `Data` struct is not relevant anymore.
    """

    @typedoc """
    The data used for the Ecspanse initialization process.
    """
    @type t :: %__MODULE__{
            operations: operations(),
            system_set_options: map()
          }

    @type operation ::
            {:add_system, Ecspanse.System.system_queue(), Ecspanse.System.t()}
            | {:add_system, :batch_systems, Ecspanse.System.t(), opts :: keyword()}
    @type operations :: list(operation())

    defstruct operations: [], system_set_options: %{}
  end

  @doc """
  The `setup/1` callback is called on Ecspanse startup and is the place to define the running systems.
  It takes an `Ecspanse.Data` struct as an argument and returns an updated struct.

  ## Examples

  ```elixir
  defmodule MyProject do
    use Ecspanse

    @impl Ecspanse
    def setup(%Ecspanse.Data{} = data) do
      data
      |> Ecspanse.Server.add_system(Demo.Systems.MoveHero)
    end
  end
  ```
  """
  @callback setup(Ecspanse.Data.t()) :: Ecspanse.Data.t()

  defmacro __using__(opts) do
    quote bind_quoted: [opts: opts], location: :keep do
      @behaviour Ecspanse

      import Ecspanse,
        only: [
          insert_resource: 2,
          init_state: 2,
          add_startup_system: 2,
          add_frame_start_system: 2,
          add_frame_start_system: 3,
          add_system: 2,
          add_system: 3,
          add_frame_end_system: 2,
          add_frame_end_system: 3,
          add_shutdown_system: 2,
          add_system_set: 2,
          add_system_set: 3
        ]

      fps_limit = Keyword.get(opts, :fps_limit, :unlimited)
      version = Keyword.get(opts, :version, 0)

      if fps_limit && not (is_integer(fps_limit) || fps_limit == :unlimited) do
        raise ArgumentError,
              "If set, the option :fps_limit must be a non negative integer in the module #{Kernel.inspect(__MODULE__)}"
      end

      unless is_integer(version) do
        raise ArgumentError,
              "The option :version must be an integer in the module #{Kernel.inspect(__MODULE__)}"
      end

      Module.register_attribute(__MODULE__, :fps_limit, accumulate: false)
      Module.put_attribute(__MODULE__, :fps_limit, fps_limit)
      Module.register_attribute(__MODULE__, :ecs_version, accumulate: false)
      Module.put_attribute(__MODULE__, :ecs_version, version)

      # THIS WILL BE THE MIX ENV OF THE PROJECT USING ECSPANSE, NOT ECSPANSE ITSELF
      if Mix.env() == :test do
        # Do not start the "real" server in test mode
        @doc false
        def child_spec(arg) do
          if arg == :test do
            payload = %{
              ecspanse_module: __MODULE__,
              fps_limit: @fps_limit,
              ecs_version: @ecs_version
            }

            %{
              id: __MODULE__,
              start: {Ecspanse.Server, :start_link, [payload]},
              restart: :permanent
            }
          else
            %{
              id: UUID.uuid4(),
              start: {Ecspanse.TestServer, :start_link, [nil]},
              restart: :temporary
            }
          end
        end
      else
        @doc false
        def child_spec(_arg) do
          payload = %{
            ecspanse_module: __MODULE__,
            fps_limit: @fps_limit,
            ecs_version: @ecs_version
          }

          %{
            id: __MODULE__,
            start: {Ecspanse.Server, :start_link, [payload]},
            restart: :permanent
          }
        end
      end
    end
  end

  @doc """
  Initializes a state at startup.
  > #### Note {: .info}
  > States can be initialized once, only at startup.
  """
  @spec init_state(Ecspanse.Data.t(), Ecspanse.State.state_spec()) :: Ecspanse.Data.t()
  def init_state(%Ecspanse.Data{operations: operations} = data, state_spec) do
    %Ecspanse.Data{data | operations: [{:init_state, state_spec} | operations]}
  end

  @doc """
  Inserts a new global resource at startup.
  See `Ecspanse.Resource` and `Ecspanse.Command.insert_resource!/1` for more info.
  """
  @spec insert_resource(Ecspanse.Data.t(), Ecspanse.Resource.resource_spec()) :: Ecspanse.Data.t()
  def insert_resource(%Ecspanse.Data{operations: operations} = data, resource_spec) do
    %Ecspanse.Data{data | operations: [{:insert_resource, resource_spec} | operations]}
  end

  @doc """
  Schedules a startup system.

  A startup system runs only once during the Ecspanse startup process. Startup systems do not take any options.

  ## Examples

    ```elixir
    Ecspanse.add_startup_system(ecspanse_data, Demo.Systems.SpawnHero)
    ```
  """
  @spec add_startup_system(Ecspanse.Data.t(), system_module :: module()) :: Ecspanse.Data.t()
  def add_startup_system(%Ecspanse.Data{operations: operations} = data, system_module) do
    system = %Ecspanse.System{
      module: system_module,
      queue: :startup_systems,
      execution: :sync,
      run_conditions: []
    }

    %Ecspanse.Data{data | operations: [{:add_system, system} | operations]}
  end

  @doc """
  Schedules a frame start system to be executed each frame during the game loop.

  A frame start system is executed synchronously at the beginning of each frame.
  Sync systems are executed in the order they were added.

  ## Options

  - See the `add_system/3` function for more information about the options.

  ## Examples

    ```elixir
    Ecspanse.add_frame_start_system(ecspanse_data, Demo.Systems.PurchaseItem)
    ```
  """

  @spec add_frame_start_system(Ecspanse.Data.t(), system_module :: module(), opts :: keyword()) ::
          Ecspanse.Data.t()
  def add_frame_start_system(%Ecspanse.Data{operations: operations} = data, system_module, opts \\ []) do
    opts = merge_system_options(opts, data.system_set_options)

    if Keyword.get(opts, :run_after) do
      Logger.warning(
        "The :run_after option is ignored by sync running systems. Those will always run in the order they were added to the data."
      )
    end

    system =
      add_run_conditions(%Ecspanse.System{module: system_module, queue: :frame_start_systems, execution: :sync}, opts)

    %Ecspanse.Data{data | operations: [{:add_system, system} | operations]}
  end

  @doc """
  Schedules an async system to be executed each frame during the game loop.

  ## Options

  - `:run_in_state` - a tuple of the state module using `Ecspanse.State` and the atom state in which the system should run.
  - `:run_not_in_state` - same as `run_in_state`, but the system will run when the state is not the one provided.
  - `:run_if` - a list of tuples containing the module and function that define a condition for running the system. Eg. `[{MyModule, :my_function}]`. The function must return a boolean.
  - `:run_after` - only for async systems - a system or list of systems that must run before this system.

  ## Order of execution

  Systems are executed each frame during the game loop. Sync systems run in the order they were added to the data's operations list.
  Async systems are grouped in batches depending on the components they are locking.
  See the `Ecspanse.System` module for more information about component locking.

  The order in which async systems run can pe specified using the `run_after` option.
  This option takes a system or list of systems that must be run before the current system.

  When using the `run_after: SystemModule1` or `run_after: [SystemModule1, SystemModule2]` option, the following rules apply:
  - The system(s) specified in `run_after` must be already scheduled. This prevents circular dependencies.
  - There is a deliberate choice to allow **only the `run_after`** ordering option. While a `run_before` option would simplify some relations, it can also introduce circular dependencies.

  Example of circular dependency:
  - System A
  - System B, run_before: System A
  - System C, run_after: System A, run_before: System B

  > #### Info  {: .info}
  > The 'run_after' option does not depend on the "before" system being executed or not
  > (eg. when the "before" system subscribes to an event that is not triggered this frame).
  > The system will be executed anyway, even if the "before" system is not executed this frame.
  > The `:run_after` option is evaluated only once, at server start-up,
  > when the async systems are grouped together into batches.
  > Then the scheduler tries to execute every system in every batch.

  ## Conditionally running systems

  The systems can be programmed to run only if some specific conditions are met.
  The conditions can be:
  - state related: `run_in_state` and `run_not_in_state`
  - custom conditions: `run_if` a function returns `true`

  `run_in_state` supports a single state. If a combination of states is needed to run a system, the `run_if` option can be used.

    ```elixir
    Ecspanse.add_system(
      ecspanse_data,
      Demo.Systems.MoveHero,
      run_if: [{Demo.States.Game, :in_market_place}]
    )

    def in_market_place do
      Demo.States.Game.get_state!() == :paused and
      Demo.States.Location.get_state!() == :market
    end
    ```

  It is important to note that the run conditions are evaluated only once per frame, at the beginning of the frame.
  So any change in the running conditions will be picked up in the next frame.

  If the system is part of a system set, and both the system and the system set have run conditions, the conditions are cumulative.
  All the conditions must be met for the system to run.

  ## Examples

    ```elixir
    Ecspanse.add_system(
      ecspanse_data,
      Demo.Systems.MoveHero,
      run_in_state: {Demo.States.Game, [:play]},
      run_after: [Demo.Systems.RestoreEnergy]
    )
    ```
  """
  @spec add_system(Ecspanse.Data.t(), system_module :: module(), opts :: keyword()) ::
          Ecspanse.Data.t()
  def add_system(%Ecspanse.Data{operations: operations} = data, system_module, opts \\ []) do
    opts = merge_system_options(opts, data.system_set_options)

    after_system = Keyword.get(opts, :run_after)

    run_after =
      case after_system do
        nil -> []
        after_systems when is_list(after_systems) -> after_systems
        after_system when is_atom(after_system) -> [after_system]
      end

    system =
      add_run_conditions(
        %Ecspanse.System{module: system_module, queue: :batch_systems, execution: :async, run_after: run_after},
        opts
      )

    %Ecspanse.Data{data | operations: [{:add_system, system} | operations]}
  end

  @doc """
  Schedules a frame end system to be executed each frame during the game loop.

  A frame end system is executed synchronously at the end of each frame.
  Sync systems are executed in the order they were added.

  ## Options

  - See the `add_system/3` function for more information about the options.

  ## Examples

    ```elixir
    Ecspanse.add_frame_end_system(ecspanse_data, Ecspanse.Systems.Timer)
    ```
  """
  @spec add_frame_end_system(Ecspanse.Data.t(), system_module :: module(), opts :: keyword()) ::
          Ecspanse.Data.t()
  def add_frame_end_system(%Ecspanse.Data{operations: operations} = data, system_module, opts \\ []) do
    opts = merge_system_options(opts, data.system_set_options)

    if Keyword.get(opts, :run_after) do
      Logger.warning(
        "The :run_after option is ignored by sync running systems. Those will always run in the order they were added to the data."
      )
    end

    system =
      add_run_conditions(%Ecspanse.System{module: system_module, queue: :frame_end_systems, execution: :sync}, opts)

    %Ecspanse.Data{data | operations: [{:add_system, system} | operations]}
  end

  @doc """
  Schedules a shutdown system.

  A shutdown system runs only once when the Ecspanse.Server terminates. Shutdown systems do not take any options.
  This is useful for cleaning up or saving the game state.

  ## Examples

    ```elixir
    Ecspanse.add_shutdown_system(ecspanse_data, Demo.Systems.Cleanup)
    ```
  """
  @spec add_shutdown_system(Ecspanse.Data.t(), system_module :: module()) :: Ecspanse.Data.t()
  def add_shutdown_system(%Ecspanse.Data{operations: operations} = data, system_module) do
    system = %Ecspanse.System{
      module: system_module,
      queue: :shutdown_systems,
      execution: :sync,
      run_conditions: []
    }

    %Ecspanse.Data{data | operations: [{:add_system, system} | operations]}
  end

  @doc """
  Convenient way to group together related systems.

  New systems can be added to the set using the `add_system_*` functions.
  System sets can also be nested.


  ## Options

  The set options that applied on top of each system options in the set.
  - See the `add_system/3` function for more information about the options.

  ## Examples

  ```elixir
  defmodule Demo do
    use Ecspanse

    @impl Ecspanse
    def setup(data) do
      data
      |> Ecspanse.add_system_set({Demo.HeroSystemSet, :setup}, [run_in_state: {Demo.States.Game, :play}])
    end

    defmodule HeroSystemSet do
      def setup(data) do
        data
        |> Ecspanse.add_system(Demo.Systems.MoveHero, [run_after: Demo.Systems.RestoreEnergy])
        |> Ecspanse.add_system_set({Demo.ItemsSystemSet, :setup})
      end
    end

    defmodule ItemsSystemSet do
      def setup(data) do
        data
        |> Ecspanse.add_system(Demo.Systems.PickupItem)
      end
    end
  end
  ```
  """
  @spec add_system_set(Ecspanse.Data.t(), {module(), function :: atom}, opts :: keyword()) ::
          Ecspanse.Data.t()
  def add_system_set(data, {module, function}, opts \\ []) do
    # add the system set options to the data
    # the Server system_set_options is a map with the key {module, function} for every system set
    data = %Ecspanse.Data{
      data
      | system_set_options: Map.put(data.system_set_options, {module, function}, opts)
    }

    data = apply(module, function, [data])

    # remove the system set options from the data
    %Ecspanse.Data{
      data
      | system_set_options: Map.delete(data.system_set_options, {module, function})
    }
  end

  @doc """
  Retrieves the Ecspanse Server process PID.
  If the data process is not found, it returns an error.

  ## Examples

    ```elixir
    Ecspanse.fetch_pid()
    {:ok, %{name: data_name, pid: data_pid}}
    ```
  """
  @spec fetch_pid() ::
          {:ok, pid()} | {:error, :not_found}
  def fetch_pid do
    case Process.whereis(Ecspanse.Server) do
      pid when is_pid(pid) ->
        {:ok, pid}

      _ ->
        {:error, :not_found}
    end
  end

  @doc """
  Queues an event to be processed in the next frame.

  ## Options

  - `:batch_key` - A key for grouping multiple similar events in different batches within the same frame.
  The event scheduler groups the events into batches by unique `{EventModule, batch_key}` combinations.
  In most cases, the key may be an entity ID that either triggers or is impacted by the event.
  Defaults to `default`, meaning that similar events will be placed in separate batches.

  ## Examples

    ```elixir
      Ecspanse.event({Demo.Events.MoveHero, direction: :up},  batch_key: hero_entity.id)
    ```
  """
  @spec event(
          Ecspanse.Event.event_spec(),
          opts :: keyword()
        ) :: :ok
  def event(event_spec, opts \\ []) do
    batch_key = Keyword.get(opts, :batch_key, "default")

    event = prepare_event(event_spec, batch_key)

    try do
      :ets.insert(Util.events_ets_table(), event)
    rescue
      e ->
        case :ets.info(Util.events_ets_table()) do
          :undefined -> reraise Util.server_not_started_error(), __STACKTRACE__
          _ -> reraise e, __STACKTRACE__
        end
    end

    :ok
  end

  defp prepare_event(event_spec, batch_key) do
    {event_module, key, event_payload} =
      case event_spec do
        {event_module, event_payload}
        when is_atom(event_module) and is_list(event_payload) ->
          validate_event(event_module)
          {event_module, batch_key, event_payload}

        event_module when is_atom(event_module) ->
          validate_event(event_module)
          {event_module, batch_key, []}
      end

    event_payload =
      Keyword.put(event_payload, :inserted_at, System.os_time())

    {{event_module, key}, struct!(event_module, event_payload)}
  end

  defp validate_event(event_module) do
    Ecspanse.Util.validate_ecs_type(
      event_module,
      :event,
      ArgumentError,
      "The module #{Kernel.inspect(event_module)} must be a Event"
    )
  end

  # merge the system options with the system set options
  # this is the reason the conditional run states are a list
  defp merge_system_options(system_opts, system_set_opts) when is_list(system_opts) and is_map(system_set_opts) do
    system_set_opts = system_set_opts |> Map.values() |> List.flatten() |> Enum.uniq()

    (system_opts ++ system_set_opts)
    |> Enum.group_by(fn {k, _v} -> k end, fn {_k, v} -> v end)
    |> Enum.map(fn {k, v} -> {k, v |> List.flatten() |> Enum.uniq()} end)
  end

  defp add_run_conditions(system, opts) do
    run_in_state = conditional_run_state(opts, :run_in_state)

    run_in_state_functions =
      Enum.map(run_in_state, fn {state_module, state} ->
        {Ecspanse.Util, :run_system_in_state, [state_module, state]}
      end)

    run_not_in_state = conditional_run_state(opts, :run_not_in_state)

    run_not_in_state_functions =
      Enum.map(run_not_in_state, fn {state_module, state} ->
        {Ecspanse.Util, :run_system_not_in_state, [state_module, state]}
      end)

    run_if =
      case Keyword.get(opts, :run_if, []) do
        {module, function} = condition when is_atom(module) and is_atom(function) -> [condition]
        conditions when is_list(conditions) -> conditions
      end

    run_if_functions =
      Enum.map(run_if, fn {module, function} ->
        {module, function, []}
      end)

    %Ecspanse.System{
      system
      | run_conditions: run_in_state_functions ++ run_not_in_state_functions ++ run_if_functions
    }
  end

  defp conditional_run_state(opts, option) do
    # This is a list. See the `merge_system_options/2` function for more info.
    # The run state conditions from systems and system sets are cumulative.
    opts
    |> Keyword.get(option, [])
    |> Enum.map(fn
      {state_module, state} when is_atom(state_module) and is_atom(state) ->
        unless is_atom(state) and state in state_module.__states__() do
          raise ArgumentError,
                "Invalid system run condition for State: #{Kernel.inspect(state_module)}. The the run condition state must be an atom from: #{Kernel.inspect(state_module.__states__())}."
        end

        [{state_module, state}]

      state_run_condition ->
        raise ArgumentError,
              "Invalid system run condition: #{Kernel.inspect(state_run_condition)}. The run condition state must be tuple in the form `{StateModule, :state}`."
    end)
    |> List.flatten()
    |> Enum.uniq()
  end
end
