libgm 0.5.1

A tool for modding, unpacking and decompiling GameMaker games
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! Contains the `GMRef` type which is used to refer to other GameMaker
//! elements.

use std::fmt;
use std::hash::Hash;
use std::hash::Hasher;

use crate::prelude::*;
use crate::util::fmt::typename;

/// A reference to another GameMaker element.
///
/// This is typically a Reference by ID in the data file format,
/// but is also used for texture page items (which are pointers).
///
/// [`GMRef`] has (fake) generic types to make it clearer which type it belongs
/// to.
/// * Example without: `pub texture_mask: GMRef`
/// * Example with: `pub texture_mask: GMRef<GMSprite>`
///
/// It can be resolved to the data it references using the `.resolve()` method,
/// which needs the vector the elements are stored in.
/// This means that removing or inserting elements in the middle of
/// the list will shift all their `GMRef`s; breaking them.
#[repr(transparent)]
pub struct GMRef<T> {
    /// The GameMaker ID / Index of this resource in the corresponding element
    /// vector.
    pub(crate) index: u32,

    /// Marker needs to be here to ignore "unused generic T" error; doesn't
    /// store any data.
    _marker: std::marker::PhantomData<T>,
}

impl<T> Copy for GMRef<T> {}
impl<T> Clone for GMRef<T> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<T> PartialEq for GMRef<T> {
    fn eq(&self, other: &Self) -> bool {
        self.index == other.index
    }
}
impl<T> Eq for GMRef<T> {}

impl<T> Hash for GMRef<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.index.hash(state);
    }
}

impl<T> From<u32> for GMRef<T> {
    fn from(index: u32) -> Self {
        Self::new(index)
    }
}

impl<T> From<usize> for GMRef<T> {
    fn from(index: usize) -> Self {
        Self::new(index as u32)
    }
}

impl<T> From<GMRef<T>> for u32 {
    fn from(gm_ref: GMRef<T>) -> Self {
        gm_ref.index
    }
}

impl<T> From<GMRef<T>> for usize {
    fn from(gm_ref: GMRef<T>) -> Self {
        gm_ref.index as Self
    }
}

impl<T> fmt::Debug for GMRef<T> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "GMRef<{}#{}>", typename::<T>(), self.index)
    }
}

impl<T> GMRef<T> {
    /// Creates a new GameMaker reference with the specified index.
    ///
    /// The fake generic type can often be omitted (if the compiler can infer
    /// it).
    #[must_use]
    pub const fn new(index: u32) -> Self {
        Self { index, _marker: std::marker::PhantomData }
    }

    /// Attempts to resolve this reference to an element in the given list by
    /// its index.
    ///
    /// Returns a reference to the element if the index is valid, or an error
    /// string if out of bounds.
    ///
    /// # Parameters
    /// - `elements_by_index`: A vector of elements indexed by `self.index`.
    ///
    /// # Errors
    /// Returns an error if `self.index` is out of bounds for the provided
    /// vector.
    pub fn resolve(self, elements_by_index: &[T]) -> Result<&T> {
        let element = elements_by_index.get(self.index as usize).ok_or_else(|| {
            format!(
                "Could not resolve {} reference with index {} in list with length {}",
                typename::<T>(),
                self.index,
                elements_by_index.len(),
            )
        })?;
        Ok(element)
    }

    /// Attempts to resolve this reference to an element in the given list by
    /// its index.
    ///
    /// Returns a reference to the element if the index is valid, or an error
    /// string if out of bounds.
    ///
    /// # Parameters
    /// - `elements_by_index`: A vector of elements indexed by `self.index`.
    ///
    /// # Errors
    /// Returns an error if `self.index` is out of bounds for the provided
    /// vector.
    pub fn resolve_mut(self, elements_by_index: &mut [T]) -> Result<&mut T> {
        let length = elements_by_index.len();
        let element = elements_by_index
            .get_mut(self.index as usize)
            .ok_or_else(|| {
                format!(
                    "Could not resolve {} reference with index {} in list with length {}",
                    typename::<T>(),
                    self.index,
                    length,
                )
            })?;
        Ok(element)
    }
}