Infinite Echoes is an interactive audio creation game that allows users to create, save, and share unique audio compositions as NFTs on the TON blockchain. The application features a drag-and-drop interface for building audio graphs with various sound generators, effects, and modifiers.

The application is designed to be entirely client-side and can be hosted on any static web server. It does not require a traditional backend; all persistent state, such as saving and sharing compositions, is handled directly on the TON blockchain.

Key Features

• Visual audio graph creation with intuitive drag-and-drop interface
• Real-time audio preview and playback
• TON wallet integration for minting and trading audio NFTs
• Cross-platform support via WebAssembly

Installation and Dependencies

Before running the project, you'll need to install the following dependencies:

Install Rust and Cargo (if not already installed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Add WebAssembly target

rustup target add wasm32-unknown-unknown

Install required tools

cargo install wasm-bindgen-cli
cargo install just
cargo install static-web-server

Building, Running, and Deployment

All the necessary commands are defined in justfile

Building the WebAssembly binary

just build

Running the development server

just run

This will start a local server at http://localhost:1234

Creating a deployment package for static file server:

just pack

This will create a deploy directory with all the necessary files for deployment.

Development

The project is a monorepo managed with just, a command runner. The justfile at the root of the project contains all the necessary commands for building, testing, and running the different parts of the application.

Project Structure

• game/: The core game logic written in Rust. It compiles to WebAssembly (WASM) and handles rendering, audio processing, and game state management.
• web_client/: The TypeScript frontend application. It provides the user interface, manages the TON wallet connection, and communicates with both the WASM game module and the TON blockchain.
• contracts/: The smart contracts written in Tact. These define the on-chain logic for creating and managing the audio pieces.
• resources/: Static assets (images, icons) used by the game.

Common Commands

Here are the most common commands you will use during development. Run them from the root of the project.

• just run: Builds all parts of the application (contracts, game, web client) and starts a local development server. This is the primary command for local development.
• just pack: Creates a production-ready build in the deploy/ directory.
• just clean: Removes all build artifacts and temporary directories (dist/, deploy/, target/, node_modules, etc.).

Component-Specific Commands

If you are working on a specific part of the application, you can use these more granular commands:

Contracts (contracts/)

• just build-contracts: Compiles the Tact smart contracts.
• just test-contracts: Runs the tests for the smart contracts.
• just deploy-contracts: Runs the deployment script for the smart contracts.

Game (game/)

• just build: Compiles the Rust code into a WebAssembly module and runs wasm-bindgen to generate JavaScript bindings. This is a prerequisite for pack and run.

Web Client (web_client/)

• just web-build: Bundles the TypeScript frontend code using Webpack.
• just web-format: Formats the TypeScript code using Prettier.
• just web-install-dependencies: Installs the npm dependencies for the web client.

How to Play

The Basics

The goal is to create a musical loop by arranging cards in the Audio Graph (the middle row of slots). You start with a Deck of cards at the bottom of the screen.

• Drag and drop cards from your Deck to the Audio Graph to build a sound sequence.
• The sound is generated by reading the cards in the graph from left to right.
• To hear your creation, press the Spacebar.

Controls

• Mouse: Drag and drop cards.
• Spacebar: Play or stop the audio from the current graph.
• Tab: Open/close your library of saved pieces.
• Escape: Open/close the Settings menu. Also closes the library or error popups.

Card Types

There are four categories of cards, identified by color:

1. Note Generators (Pink): These cards create musical notes. They are the starting point of your sound.
2. Note Effects (Yellow): These cards modify the notes from the generators. They must be placed after Note Generators. Examples include creating chords or changing the rhythm.
3. Oscillators (Blue): These cards produce the actual sound wave (e.g., Sine, Square). A valid audio graph must have at least one oscillator.
4. Audio Effects (Purple): These cards modify the sound produced by the oscillator. They must be placed after an Oscillator. Examples include Distortion, Reverb, and Filters.

Creating Sound

A graph must contain at least one Note Generator and one Oscillator to produce sound. The audio signal flows from left to right: Note Generators create the melody, which is then played by an Oscillator. The sound from the Oscillator then passes through any subsequent Audio Effects.

Saving & Remixing (TON Blockchain)

• Connect Wallet: To save your creations, you must connect a TON wallet.
• Saving (Minting): When you save a piece, it is minted as an NFT-like smart contract on the TON blockchain. This action requires a small transaction fee (gas) paid in TON coin. You can name your piece in the Settings menu (Escape) before saving.
• Library: Press Tab to view all the pieces you own. Clicking a piece loads it into the audio graph.
• Remixing: Load any piece from your library, make changes, and save it. The new piece will be a new NFT that is linked to the original, crediting it as a "remix."
• Starting Fresh: In the Settings menu (Escape), click the "Init" button to clear the audio graph and start a new creation from scratch.

The Audio Engine

The game's audio is powered by the Web Audio API, a browser technology that allows for real-time sound synthesis and processing.

• When you press play, your card sequence in the Audio Graph is translated into a network of virtual audio nodes (oscillators, filters, etc.).
• Note events are scheduled with precise timing based on the composition's BPM (beats per minute) to ensure a synchronized, musical loop.
• This entire system runs directly in your browser, compiling from Rust to WebAssembly for high performance.

License

This project is licensed under the MIT License - see the LICENSE file for details.