.. _api_sm64:

==========
sm64.hpp
==========

The core libsm64 interface.

.. cpp:namespace:: pancake
.. cpp:class:: sm64
  
  Interface class to libsm64. It's quite primitive at the moment.
  
  **Constructors**
  
  .. note:: 
    Safety cannot be guaranteed with this class, this is simply due to how low-level it is.
  
  .. cpp:function:: sm64(const char* path)
    
    Loads libsm64 from the DLL at the specified path.
    
    :param path: C string with the path to the DLL
    
  .. cpp:function:: sm64(std::string path)
  
    Loads libsm64 from the DLL at the specified path.
    
    :param path: String with the path to the DLL
    
  .. cpp:function:: sm64(std::filesystem::path path)
  
    Loads libsm64 from the DLL at the specified path.
    
    :param path: Path to the DLL.
  
  **Access functions**
    
  .. cpp:function:: template<typename T> T& get(std::string expr)
    
    Gets a reference to a variable from libsm64.
    
    .. note::
      This method performs type checking. If you don't like that, use :cpp:func:`get_unsafe()` instead.
    
    :tparam T: The type of the returned reference
    :param expr: A valid :ref:`accessor expression <about_accessor_expressions>`
    :throws std::domain_error: if the accessor expression does not refer to a base type
    :throws pancake::type_error: if the accessor expression's type doesn't match ``T``
    :throws std::invalid_argument: if the accessor expression is somehow invalid
    
  .. cpp:function:: void* get_unsafe(std::string expr)
    
    Gets a void pointer to a variable from libsm64.
    
    .. warning::
      This method doesn't perform type checking. If you care about type safety, use :cpp:func:`get()` instead.
    
    :tparam T: The type of the returned reference
    :param expr: A valid :ref:`accessor expression <about_accessor_expressions>`
    :throws std::domain_error: if the accessor expression does not refer to a base type
    :throws std::invalid_argument: if the accessor expression is somehow invalid
  
  .. cpp:function:: const std::variant<double, int64_t, nullptr_t> constant(std::string name) const
  
    Gets a constant, returning the specified type in a variant.
    
    :param name: the name of the constant
    :return: the requested constant, wrapped in a variant. If the constant is defined with no value,\
      returns ``nullptr``.
  
  .. cpp:function:: void advance()
    
    Advances the game by 1 frame.
    
  **Savestate functions**
  
  .. cpp:class:: savestate final
  
    Opaque class containing savestate buffers.
    The implementation is platform-specific and non-extensible.
  
  .. cpp:function:: savestate alloc_svst() const
    
    Allocates a savestate buffer bound to this :cpp:class:`sm64`.
    
    :return: An empty savestate buffer
    
  .. cpp:function:: void save_svst(savestate& st) const
  
    Saves a savestate buffer.
    
    :param st: The savestate to save to.
    :throws std::domain_error: if the passed-in savestate is bound to a different :cpp:class:`sm64`
    
  .. cpp:function:: void load_svst(const savestate& st)
  
    Loads a savestate buffer.
    
    :param st: The savestate to load from.
    :throws std::domain_error: if the passed-in savestate is bound to a different :cpp:class:`sm64`