Rust Backend Currency System

1. Designing a Safe Wallet: The Power of Encapsulation

Before we write any code, let's think about the design. A character's wallet needs to store their money, but we also need to control how that money is changed. We can't have a situation where a bug accidentally sets a character's balance to a negative number, or where money is added without a proper transaction.

This is a perfect scenario to apply the principle of encapsulation. We will hide the wallet's internal balance from the outside world and only expose a set of public functions (methods) to interact with it, like deposit and withdraw. This ensures all changes to the balance happen in a controlled, predictable way.

This concept is fundamental to building reliable software. The following article uses a great vending machine analogy and then applies the principle to a BankAccount struct, which is almost identical to the Wallet we're about to build.

This next resource provides another concrete example of an encapsulated BankAccount within a Rust module. It reinforces the pattern of a private balance field with public deposit, withdraw, and get_balance methods.

From these resources, our design for the Wallet is clear:

• A Wallet struct.
• A private field inside, balance: f64.
• A public new() function to create a wallet with a starting balance.
• A public deposit() method to add money.
• A public withdraw() method to remove money, which fails if funds are insufficient.
• A public balance() method to check the current balance.

2. Implementing Behavior with impl

To attach these functions (like deposit and withdraw) to our Wallet struct, we use an impl (implementation) block in Rust.

Methods inside an impl block that need to modify the struct's data, like deposit, must declare that they are taking a mutable reference to the instance. This is done by specifying the first parameter as &mut self. This is a key concept in Rust that ensures data safety.

This video provides an excellent, practical demonstration of creating methods that mutate a struct's state.

To reinforce the syntax, the following video also provides a solid walkthrough of creating structs and impl blocks.

3. Building the Wallet in Rust

Now, let's combine these concepts and write the code.

Step 3.1: Define the Wallet Struct and impl Block

In your Rust project (e.g., in src/main.rs or a new src/economy.rs module file), add the following code. We'll derive Debug to make it easy to print, and serde's Serialize and Deserialize for our future save/load system.

use serde::{Serialize, Deserialize};




#[derive(Serialize, Deserialize, Debug)]
pub struct Wallet {
    // This field is private by default because we don't add `pub`.
    balance: f64,
}

impl Wallet {
    /// Creates a new Wallet with a specified starting balance.
    /// Ensures the starting balance is not negative.
    pub fn new(starting_balance: f64) -> Self {
        Wallet {
            balance: if starting_balance > 0.0 { starting_balance } else { 0.0 },
        }
    }

    /// Returns the current balance.
    pub fn balance(&self) -> f64 {
        self.balance
    }

    /// Adds a specified amount to the balance.
    /// The amount must be positive.
    pub fn deposit(&mut self, amount: f64) {
        if amount > 0.0 {
            self.balance += amount;
        }
    }

    /// Attempts to withdraw a specified amount from the balance.
    /// Returns Ok(()) on success or an Err(&str) on failure.
    pub fn withdraw(&mut self, amount: f64) -> Result<(), &'static str> {
        if amount <= 0.0 {
            return Err("Withdrawal amount must be positive.");
        }
        if self.balance < amount {
            return Err("Insufficient funds.");
        }

        self.balance -= amount;
        Ok(())
    }
}

Notice a few key details here:

• The balance field is private because it lacks the pub keyword. Code outside this module cannot write my_wallet.balance = 1000.0;.
• The withdraw method returns a Result<(), &'static str>. This is idiomatic Rust for operations that can fail. It forces the calling code to handle both the success (Ok) and failure (Err) cases, preventing bugs.

Step 3.2: Integrate the Wallet into the Character Struct

Now, find the Character struct you created in Module 3. We'll add the Wallet as a new field.

Assuming your Character struct looks something like this, make the following additions:

// You'll need to use your new Wallet struct
// If it's in another file, you might write: mod economy; use economy::Wallet;




#[derive(Serialize, Deserialize, Debug)]
pub struct Character {
    pub name: String,
    // ... other fields like personality, traits, age ...
    pub wallet: Wallet, // Add the wallet here
}

impl Character {
    // Update your character constructor
    pub fn new(name: String, /*...other params...*/, starting_money: f64) -> Self {
        Character {
            name,
            // ... initialize other fields ...
            wallet: Wallet::new(starting_money), // Create a new wallet for the character
        }
    }
}

Step 3.3: Test the Implementation

It's always a good idea to test new logic. You can add a temporary test function to main to see it in action.

fn main() {
    // Create a new character with $500
    let mut character = Character::new("Alex".to_string(), 500.0);
    println!("Initial state: {:?}", character);

    // Deposit money
    character.wallet.deposit(150.50);
    println!("After deposit: balance is ${:.2}", character.wallet.balance());

    // Try to withdraw more money than available
    match character.wallet.withdraw(1000.0) {
        Ok(_) => println!("Withdrawal successful."),
        Err(e) => println!("Withdrawal failed: {}", e),
    }
    println!("After failed withdrawal: balance is ${:.2}", character.wallet.balance());

    // Successfully withdraw money
    match character.wallet.withdraw(200.0) {
        Ok(_) => println!("Withdrawal successful."),
        Err(e) => println!("Withdrawal failed: {}", e),
    }
    println!("Final state: {:?}", character);
}

When you run this with cargo run, you should see the balance change correctly and the error message for the failed withdrawal, proving your encapsulated system works as intended.

Conclusion

Excellent work! You have successfully implemented a core economic feature for our game. By creating an encapsulated Wallet system, you've not only given characters a way to manage money but also built it in a safe, robust, and maintainable way that will prevent future bugs.

Key Takeaways:

• Encapsulation in Rust: We made our Wallet robust by keeping its balance field private and exposing public methods (deposit, withdraw, balance) for controlled interactions.
• Mutating Methods: Methods that change a struct's internal state, like deposit and withdraw, require a mutable reference to the instance (&mut self).
• Error Handling with Result: Using Result for operations that can fail (like withdraw) is a core Rust pattern that forces developers to handle errors gracefully.
• Data Model Integration: The Wallet is now a fundamental part of our Character data model, ready to be used by other game systems.

Preview of the Next Lesson:
Now that our characters have wallets, they need a way to get money and a reason to spend it. In the next lesson, we will implement the other side of this coin: a basic income source (like a daily stipend) and recurring bills. This will put our new Wallet methods to immediate use and make the simulation feel more alive.