TokenTorch README

(DO NOT RUN MORE THAN ONE.) If you try to reload a world the
system is going to overwrite the existing world data and cause
problems. This is still highly iterative work, I'm delegating
complexity for foundations like world generation, fluid
simulation, AI, crafting, vehicles, magic, etc. and most of the
dialing and polish features will be bolted on as the systems
starts to work as a whole.

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.

If you want enemies install ollama and in the terminal run
ollama run phi3 to start the PHI3 Arachnoids.

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, lakes,
  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:

• Dynamic Minds:
  Each AI agent has a unique "mind" that expresses its interactions
  with the world. The neural net will process dynamic inputs (visual,
  auditory, contextual) as prompts and output actions (movement, mining,
  building). The goal is for agents to learn complex behaviors like
  pathfinding, resource gathering, construction, and even social
  interactions with players and other agents managed by the system
  interpretations and a "macro-memory" that stores system keys for
  "prompting reality" and securing the choices of the LLM.

• Polymorphic Memory:
  Each agent has a "memory" that stores past experiences, observations,
  and learned knowledge. This memory will be dynamic and can be
  updated by the system to inform decision-making. For example,
  an agent might gain a memory of the location of a valuable ore vein or a
  dangerous cave system and use that information in future actions.
  The memory system will be designed to allow for both short-term
  recall (recent events) and long-term memory (important discoveries,
  learned skills). The agent will also summarize it's daily life when
  it goes to sleep and store that summary in a memory for future reference.

• Systematic Choice:
  The neural net will be designed to make systematic choices based on
  its learned knowledge and current context. For example, if an agent
  learns that mining a certain type of ore is profitable, it might
  prioritize that activity in its decision-making. The goal is for
  agents to develop their own unique "personalities" and play styles
  based on their experiences and learning. This will operate by having the
  system send periodic prompts to the agent requesting choices based on
  the surrounding context, then the system reads what the agent thought
  and uses that to guide the agent's actions.

• Factions & Reputation:
  The system will interpret how the monsters and villagers are aligned
  and have them join factions based on their interactions. If a player
  repeatedly helps a villager, it might develop a positive reputation and
  become friendly. The goal is for the world to feel dynamic and
  responsive to player actions, with NPCs that have their own motivations
  and relationships. Numerous factions will exist.

• Emergent Behaviors:
  As agents learn and interact with the world, I hope to see emergent
  behaviors that I didn't explicitly program. For example, agents might
  develop their own strategies for mining or building, or they might form
  alliances with other agents. The goal is for the world to feel alive and
  unpredictable, with agents that can surprise players with their actions.

  The combination of dynamic minds, polymorphic memory, and systematic
  choice, could be the next frontier of game development where the AI can
  adapt and interact in complex ways within the game world. This is the
  long-term vision for the project, and I'm excited to see how it evolves
  over time.

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:

The PHI3 Arachnoids are plotting their attacks!

MADNESS:

I'll try to make this more user-friendly ASAP!

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