Introduction

Welcome to Protibuild - an open-source protein simulator and builder that brings molecular biology to life through interactive 3D visualization.

What is Protibuild?

Protibuild is a desktop application designed for researchers, students, and enthusiasts to:

• Visualize proteins in realistic 3D environments
• Explore amino acid structures with accurate ball-and-stick models
• Interact with molecules by picking up and moving objects in 3D space
• Switch between project templates for different viewing modes

Key Features

Molecular Visualization

• Ball-and-stick model for accurate molecular representation
• CPK coloring - standard chemical colors for each element
  • Hydrogen (H): White
  • Carbon (C): Gray
  • Nitrogen (N): Blue
  • Oxygen (O): Red
  • Sulfur (S): Yellow

Supported Molecules

• All 20 standard amino acids with accurate atomic positions and bond connectivity
• Dev Cube - a simple rotating cube for development testing

Interactive Controls

• First-person camera navigation
• Pick up and move objects in 3D space
• Adjust object distance with scroll wheel

Technology

Protibuild is built with:

• Bevy 0.18 - A refreshingly simple data-driven game engine
• Rust - For performance and safety

Getting Started

1. Launch the application - You’ll start in the “Dev Cube” project
2. Open the File menu - Click “File” in the top-left corner
3. Select a project - Choose “Amino Acids” to see all 20 standard amino acids
4. Navigate with WASD - Press C to capture your cursor, then use movement keys
5. Interact with objects - Hover over molecules and click to grab them

Support the Project

If you find Protibuild useful, consider supporting its development:

Repository: https://github.com/alexandercoop562/protibuild

Installation

This guide covers how to install and run Protibuild on your system.

Prerequisites

Before installing Protibuild, ensure your system meets the requirements:

System Requirements

• Operating System: Windows, macOS, or Linux
• Rust: Latest stable Rust (see rustup)
• Graphics: WebGL 2.0 capable GPU

Bevy Dependencies

Protibuild uses the Bevy game engine, which requires certain system dependencies. Follow the Bevy setup guide for your specific OS.

Common dependencies include:

• On Linux: libudev, libasound2, libxkbcommon
• On macOS: Xcode command line tools
• On Windows: Visual Studio Build Tools

Installation Methods

From Source (Recommended)

1. Clone the repository

   git clone https://github.com/alexandercoop562/protibuild.git
   cd protibuild
   

2. Build and run

   make run
   

   Or directly:

   cargo run -p protibuild
   

Using Make Commands

The project includes a Makefile with common commands:

Code Quality Commands

If you want to check code quality separately:

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features -- -D warnings

# Security audit
cargo audit

# License check
cargo deny check

Running the Application

Development Build

For development with faster compile times, use dynamic linking:

cargo run -p protibuild

The application will launch with a window showing the 3D viewport.

First Launch

On first launch:

1. A window opens showing the “Dev Cube” project
2. Click the File tab to access project templates
3. Press C to capture your cursor and enable camera controls
4. Use WASD + Space/Shift to move around

Troubleshooting

Compilation Errors

If you encounter compilation errors:

1. Ensure Rust is up to date: rustup update
2. Clear build cache: cargo clean
3. Rebuild: cargo build -p protibuild

Missing Dependencies

If the application fails to start with missing library errors:

• Linux: Install system packages for Bevy (see Bevy setup guide)
• macOS: Run xcode-select --install
• Windows: Ensure Visual Studio Build Tools are installed

Performance Issues

If the application runs slowly:

• Ensure GPU drivers are up to date
• Try running in release mode: cargo run -p protibuild --release

Controls

Protibuild uses an intuitive control scheme that allows you to navigate the 3D space and interact with molecular structures efficiently.

Cursor Capture

Before you can look around or move, you need to capture the mouse cursor:

Important: You must capture the cursor (press C) before you can use WASD movement or look around with the mouse. Release the cursor (Escape) when you need to interact with UI elements like the File menu.

Camera Movement

Mouse Look

• Mouse Movement - Look around (only when cursor is captured)
• Movement is relative to your current viewing direction

Navigation Keys

Movement is relative to your current viewing direction:

• W/S moves along the horizontal plane (ignoring vertical tilt)
• A/D moves sideways
• Space/Shift moves vertically

Object Interaction

Selecting and Moving Objects

Note: Cursor must be captured to interact with objects.

When you grab an object, it follows your cursor at a fixed distance. You can move around while holding the object.

Adjusting Distance

Distance range: 0.5 to 50 units

Reference Grid

The 3D grid provides spatial reference:

The grid automatically updates as you move through the space, always centering on your current position.

Quick Reference

Tips

• Capture the cursor (C) when you want to look around freely and interact with objects
• Release the cursor (Escape) when you need to interact with UI elements like the File menu
• Objects can be picked up from a distance - you don’t need to be right next to them
• Use the scroll wheel to position objects precisely at your desired distance
• The Dev Cube rotates automatically - try picking it up and moving around!

Interface

Protibuild features a minimalist interface designed to keep the focus on molecular visualization.

Main UI Elements

Tab Bar

Located at the top of the window, the tab bar provides access to the File menu:

• File Tab - Opens the project selection menu (active by default)
• Default Tab - A placeholder tab for future features

File Menu

The File menu appears when you click the “File” tab. It contains:

1. Application Title - “Protibuild” displayed prominently
2. Templates Section - List of available project templates
3. Project Buttons - Click to switch between projects

Project Buttons

The buttons highlight on hover and trigger a project switch when clicked.

Visual Feedback

Object Highlighting

When you hover over an interactive object:

• A white wireframe cube appears around the object
• This indicates the object can be picked up

When holding an object:

• The white highlight persists
• The object follows your cursor

Cursor States

Layout

+--------------------------------------------------+
|  [File]  [Default]                    (Tab Bar) |
+--------------------------------------------------+
|                                                  |
|                                                  |
|              3D Viewport                         |
|         (Molecular Visualization)                |
|                                                  |
|                                                  |
+--------------------------------------------------+

The 3D viewport occupies the entire window background. The UI overlays are minimal and non-intrusive.

Design

The interface uses a dark theme:

• Background: Dark gray (#121212)
• Text: Light gray (#f2f2f2)
• Buttons: Blue-gray with hover highlights
• Active elements: Lighter background for selected items

This ensures good contrast for viewing molecular structures while providing a modern, clean aesthetic.

Projects

Protibuild uses a project-based system that allows you to switch between different molecular scenes. Each project defines which objects are loaded and the initial camera position.

Switching Projects

1. Click the File tab in the top-left corner of the screen
2. The File menu will open showing available templates
3. Click on a project button to load that scene
4. The view will automatically switch to the Default tab

Available Templates

Dev Cube

A simple development test project featuring:

• A single gray rotating cube at the world origin
• Useful for testing camera controls and object interaction
• Camera starts at position (0, 2, 5) looking at origin

This is the default project when the application starts.

Amino Acids

Displays all 20 standard amino acids arranged in a 4-row grid layout:

Row 1: Small & Aliphatic

• Glycine (GLY)
• Alanine (ALA)
• Valine (VAL)
• Leucine (LEU)
• Isoleucine (ILE)
• Methionine (MET)
• Proline (PRO)

Row 2: Aromatic

• Phenylalanine (PHE)
• Tyrosine (TYR)
• Tryptophan (TRP)

Row 3: Polar & Charged

• Serine (SER)
• Threonine (THR)
• Cysteine (CYS)
• Asparagine (ASN)
• Glutamine (GLN)
• Aspartic Acid (ASP)
• Glutamic Acid (GLU)

Row 4: Basic

• Lysine (LYS)
• Arginine (ARG)
• Histidine (HIS)

Each amino acid is labeled with its three-letter code and positioned with appropriate spacing for easy viewing and comparison.

Camera starts at position (0, 10, 15) looking at the center of the grid.

Project Structure

Projects are defined in code using the Project struct with:

• Name: Display name of the project
• Description: Brief description shown in the UI
• Objects: List of molecules to spawn
• Camera: Initial position and look target

Adding New Projects

To add a new project template:

1. Define the objects using ProjectObject helpers
2. Set initial camera position and target
3. Add a button in the UI tab bar

See projects/templates.rs for implementation details.

Chemistry

Protibuild provides accurate molecular visualization using the ball-and-stick model. This section documents the chemical elements and amino acids supported by the application.

Elements

Protibuild supports 5 common elements found in organic molecules and proteins:

CPK Coloring

The application uses standard CPK (Corey-Pauling-Koltun) coloring, which is the industry standard for molecular visualization:

• Hydrogen (H): White - Represented as small white spheres
• Carbon (C): Gray - The backbone of organic molecules
• Nitrogen (N): Blue - Found in amino groups
• Oxygen (O): Red - Found in carbonyl and hydroxyl groups
• Sulfur (S): Yellow - Found in cysteine and methionine

Visualization

• Atoms are rendered as spheres with radii proportional to their covalent radii (scaled by 0.3 for visibility)
• Bonds are rendered as gray cylinders connecting atoms
• Atom size reflects the element type - Hydrogen is smallest, Sulfur is largest

Amino Acids

Protibuild supports all 20 standard amino acids found in proteins. Each amino acid is modeled with accurate atomic positions and bond connectivity.

Amino Acid Reference

Structure

Each amino acid is rendered as a parent entity containing:

1. Atom entities - Individual atoms positioned at their correct 3D coordinates
2. Bond entities - Cylinders connecting bonded atoms
3. Metadata - Amino acid code, residue number, and chain ID

Data Source

Amino acid structures are loaded from a JSON configuration file (amino_acids.json) which contains:

• Atom positions (x, y, z coordinates)
• Atom names (e.g., “CA”, “CB”, “N”, “O”)
• Bond connectivity (pairs of atom indices)

This allows easy extension with additional molecules or modified structures.