TokenTorch README

(Sorry if my commit messages are broken in places, I need sleep.)

For the people running the project:

Always initiate the server first, cleint server joining is
automatic at the moment. Just run server.py then run main.py.

Welcome to my highly experimental voxel engine and physics
simulator, built from scratch in Python using ModernGL and
Pyrr. This project is a sandbox for exploring GPU-accelerated
cellular automata (via Warp), procedural world generation,
custom concurrency models, and the main feature I'm planning
is PyTorch neural net AI that can learn to navigate / play
along-side the players.

Features

• Procedural World Generation: 32x32 KM world with 70 KM
  depth and height voxel terrain with caves, mountains, oceans,
  and biomes.

• Multiplayer Networking: UDP-based client-server
  architecture with chunk state synchronization.

• GPU-Accelerated Water Simulation: Cellular automata fluid
  simulation running entirely on the GPU for real-time performance.

• Custom Concurrency Model: Token-based task orchestration
  framework for managing background workloads and server
  operations. (See tokengate/operations_coordinator.py for a
  look into how I've implemented the threading.)

Performance

• The engine runs at 130 FPS on a 4070 with 850 chunks on
  screen and 1700 loaded in memory.

• The profiler reports minimal latency in rendering and 1% lows
  are optimal.

I cannot garantee performance on low-end hardware and large
view distances. The current implmentation uses a large view
range, to change it look at these settings:

render_dist_h, render_dist_v = 5, 5 # Inside "client.py" do not  
# exceed these values unless you have extreme hardware  
# capabilities. This range is 10x10x10 chunks (16x16x16 voxels  
# each) which is already a very large area to render and simulate. 

# render_dist_h = Horizontal
# render_dist_v = Vertical

Future Plans

Main Feature:

PyTorch Nerual Net AI: This is the next big frontier for
the project. I want to implement a custom neural net using
PyTorch that can learn to navigate the voxel world, mine
resources, and build structures. (Planned for 1-5+ years in
development.)

Nerual Net Features Include:

• Reinforcement Learning: The agent will learn through
  trial and error, receiving rewards for gathering resources,
  building structures, and surviving in the world or killing
  players as monsters.

• Reward System: The reward system will be carefully
  designed to encourage complex behaviors. For example,
  gathering resources will yield small rewards, while building
  a structure or successfully attacking a player will yield
  larger rewards. There will also be a second dimension
  providing a space for dead agents to become "ghosts" that can
  still interact with the world and influence the living,
  but with a different reward structure. (This will prevent
  "over-dying" so agents remain cohesive if they are attacked
  frequenty and or consitently engage the negative reponses of the
  system.)

• Custom Architecture: In this system no neural nets are
  discarded. Instead the agents will be refined in the other
  dimension as well as inter-agent "reforging" that allows them
  to share and combine learned behaviors. This will be a unique
  twist on the standard reinforcement learning loop, allowing
  for emergent behaviors and a dynamic ecosystem of agents that
  can evolve over time. The architecture will be designed to
  allow for experimentation with different neural net designs
  and learning algorithms. (For instance: Monsters should
  share behavior and learn from each other while communicating
  player positions and weaknesses, while villagers may share
  building strategies and resource gathering techniques.)

• Types of Neural Net: I plan to experiment with various
  architectures, including convolutional neural networks (CNNs)
  for spatial awareness, recurrent neural networks (RNNs) for
  memory and planning, and transformer-based models for complex
  decision-making. They will be joined as a hybrid architecture
  that can leverage the strengths of each in an NPC context.

• NPC Types: Some of the intended NPCs include both
  monsters and friendly villagers. The monsters will have
  aggressive behaviors and will learn to hunt the player, while
  the villagers will focus on gathering resources, building
  structures, and trading with the player.

The other main features include Warp automata, continental
world generation, techno-magi-alchemy crafting systems, with
vehicles as well as aircraft and locomotives.

IMPORTANT: This project experimental!

There are a number of people using this but please be aware
that this is an experimental sandbox project and not a polished
open-source library yet. The code is in active development and
subject to significant changes, and there are likely to be
rough edges, bugs, and refactors as I iterate on the design.

Contributing code is welcome but please be aware that the
codebase is actively changing frequently. Make sure to read
commits if you want to modify this for yourself or submit a PR
if you have something to contribute.

Gallery:

MADNESS:

Only a true mad man would run numerous GPU kernels from a
random repo... Maximum respect.