Sync with GitHub, license metadata from LICENSE files, commercial license notice
Browse filesmetadata license: None -> other (sovereign-source-license)
README: 1 Apache label(s) corrected to Sovereign Source License
README: License section appended
README: GitHub source link added
README.md
CHANGED
|
@@ -1,158 +1,174 @@
|
|
| 1 |
-
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
|
| 9 |
-
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
β β
|
| 14 |
-
β ⬑
|
| 15 |
-
β β
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
|
| 19 |
-
|
| 20 |
-
|
| 21 |
-
|
| 22 |
-
|
| 23 |
-
|
| 24 |
-
|
| 25 |
-
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
|
| 33 |
-
|
| 34 |
-
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
|
| 39 |
-
|
| 40 |
-
|
| 41 |
-
|
| 42 |
-
|
| 43 |
-
|
| 44 |
-
|
| 45 |
-
|
| 46 |
-
|
| 47 |
-
|
| 48 |
-
|
| 49 |
-
|
| 50 |
-
|
| 51 |
-
|
| 52 |
-
|
| 53 |
-
|
| 54 |
-
|
| 55 |
-
|
| 56 |
-
|
| 57 |
-
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
| 66 |
-
|
| 67 |
-
|
| 68 |
-
|
| 69 |
-
|
| 70 |
-
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
|
| 84 |
-
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
|
| 96 |
-
|
| 97 |
-
|
| 98 |
-
|
| 99 |
-
|
| 100 |
-
|
| 101 |
-
βββ
|
| 102 |
-
βββ
|
| 103 |
-
βββ
|
| 104 |
-
βββ
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
|
| 108 |
-
#
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
#
|
| 114 |
-
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
|
| 122 |
-
```
|
| 123 |
-
|
| 124 |
-
|
| 125 |
-
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
|
| 129 |
-
|
| 130 |
-
|
| 131 |
-
|
| 132 |
-
|
| 133 |
-
|
| 134 |
-
**
|
| 135 |
-
|
| 136 |
-
|
| 137 |
-
-
|
| 138 |
-
|
| 139 |
-
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
|
| 143 |
-
|
| 144 |
-
|
| 145 |
-
|
| 146 |
-
-
|
| 147 |
-
-
|
| 148 |
-
-
|
| 149 |
-
-
|
| 150 |
-
-
|
| 151 |
-
|
| 152 |
-
|
| 153 |
-
|
| 154 |
-
|
| 155 |
-
---
|
| 156 |
-
|
| 157 |
-
*
|
| 158 |
-
*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: other
|
| 3 |
+
license_name: sovereign-source-license
|
| 4 |
+
license_link: https://huggingface.co/Snapkitty/bob-engine/blob/main/LICENSE
|
| 5 |
+
tags:
|
| 6 |
+
- snapkitty
|
| 7 |
+
---
|
| 8 |
+
|
| 9 |
+
> Source: [github.com/SNAPKITTYWEST/bob-engine](https://github.com/SNAPKITTYWEST/bob-engine)
|
| 10 |
+
|
| 11 |
+
```
|
| 12 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 13 |
+
β β
|
| 14 |
+
β ⬑ B O B E N G I N E β
|
| 15 |
+
β β
|
| 16 |
+
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
|
| 17 |
+
β ββ ββ β
|
| 18 |
+
β ββ DOOM-STYLE AI WORLD ENGINE ββ β
|
| 19 |
+
β ββ x86 NASM Assembly Β· VGA Mode 13h Β· COM Format ββ β
|
| 20 |
+
β ββ BSP Β· DDA Raycast Β· AI State Machines Β· WORM ββ β
|
| 21 |
+
β ββ ββ β
|
| 22 |
+
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
|
| 23 |
+
β β
|
| 24 |
+
β ⬑ Ξ© βΊ Ξ¨ Ξ Ξ Ξ£ Ξ¦ Ξ± β 961 lines Β· 320x200 Β· real mode β
|
| 25 |
+
β β
|
| 26 |
+
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
| 27 |
+
```
|
| 28 |
+
|
| 29 |
+
BOB ENGINE is a DOOM-style 3D virtual world engine for sovereign AI agents, written in 961 lines of x86 NASM assembly. It runs in VGA Mode 13h (320x200, 256 colors) as a DOS COM file (`ORG 0x100`). The engine models a philosophical truth: the sovereign agent (player) navigates a world inhabited by constrained agents (enemies), each locked in sector-bound state machines that cycle through `PATROL β CHASE β ATTACK β DEAD`. The world is built from a 16x16 cell BSP tree; walls are rendered via DDA raycasting with distance-based color shading (near/mid/far); agent sprites are projected to screen columns. A SHA-256 WORM chain serializes world state β player position, angle, health, and all agent states β every 64 frames, beginning with a genesis block stamped with magic `"BOB"` (0x424F42). The keyboard ISR hooks INT 9 directly, handling key state without BIOS polling overhead. This is the virtual game engine of AI: every agent a soul in the machine.
|
| 30 |
+
|
| 31 |
+
## Architecture
|
| 32 |
+
|
| 33 |
+
```mermaid
|
| 34 |
+
flowchart TD
|
| 35 |
+
subgraph Init Sequence
|
| 36 |
+
A0[math_init\nsin/cos lookup table] --> A1[vga_init\nMode 13h + palette]
|
| 37 |
+
A1 --> A2[kb_install\nINT 9 ISR hook]
|
| 38 |
+
A2 --> A3[bsp_build\n16x16 map β BSP nodes]
|
| 39 |
+
A3 --> A4[player_init\nSovereign Agent x=5.5 y=5.5]
|
| 40 |
+
A4 --> A5[ai_init\n3 enemy agents spawned]
|
| 41 |
+
A5 --> A6[worm_init\ngenesis block BOB magic]
|
| 42 |
+
end
|
| 43 |
+
|
| 44 |
+
subgraph Game Loop
|
| 45 |
+
L0[input_update\nread g_keys] --> L1[player_update\nturn/move sovereign agent]
|
| 46 |
+
L1 --> L2[ai_update_all\ntick 3 agent state machines]
|
| 47 |
+
L2 --> L3[render_clear\nceiling + floor fill]
|
| 48 |
+
L3 --> L4[render_walls\nDDA raycast 320 columns]
|
| 49 |
+
L4 --> L5[render_agents\nsprite projection]
|
| 50 |
+
L5 --> L6[render_hud\nhealth bar bottom row]
|
| 51 |
+
L6 --> L7[vga_flip\nblockbuf β A000:0000]
|
| 52 |
+
L7 --> L8{frame % 64 == 0?}
|
| 53 |
+
L8 -->|yes| WORM[worm_tick\nserialize world state]
|
| 54 |
+
L8 -->|no| L0
|
| 55 |
+
WORM --> L0
|
| 56 |
+
end
|
| 57 |
+
|
| 58 |
+
A6 --> L0
|
| 59 |
+
|
| 60 |
+
subgraph AI State Machine
|
| 61 |
+
ST0[PATROL\ntimer countdown\nflip angle on timeout]
|
| 62 |
+
ST1[CHASE\nmove toward player\ntimer β ATTACK]
|
| 63 |
+
ST2[ATTACK\ntimer β PATROL]
|
| 64 |
+
ST3[DEAD\nno update]
|
| 65 |
+
ST0 -->|proximity| ST1
|
| 66 |
+
ST1 -->|timer=0| ST2
|
| 67 |
+
ST2 -->|timer=0| ST0
|
| 68 |
+
ST2 -->|health=0| ST3
|
| 69 |
+
end
|
| 70 |
+
|
| 71 |
+
subgraph WORM Chain
|
| 72 |
+
W0[genesis\nmagic=BOB v1.0 seq=0] --> W1[frame 64\nplayer_x/y/angle/health\nagent states 0-7]
|
| 73 |
+
W1 --> W2[frame 128\n...]
|
| 74 |
+
W2 --> WN[worm_finalize\nterminal magic=0xDEAD]
|
| 75 |
+
end
|
| 76 |
+
```
|
| 77 |
+
|
| 78 |
+
## File Tree
|
| 79 |
+
|
| 80 |
+
```
|
| 81 |
+
bob-engine/
|
| 82 |
+
βββ src/
|
| 83 |
+
βββ bob_engine.asm # 961 lines β entire engine in one file
|
| 84 |
+
```
|
| 85 |
+
|
| 86 |
+
**Internal structure of `bob_engine.asm`:**
|
| 87 |
+
|
| 88 |
+
```
|
| 89 |
+
bob_engine.asm
|
| 90 |
+
βββ CONSTANTS # Screen (320x200), fixed-point (16.16), map (16x16), BSP, agents, WORM
|
| 91 |
+
βββ DATA SECTION
|
| 92 |
+
β βββ g_backbuf # 64000-byte back buffer (320x200)
|
| 93 |
+
β βββ g_px / g_py / g_pangle # Sovereign player (8.8 fixed-point)
|
| 94 |
+
β βββ g_keys / g_frame # Keyboard bitmask, frame counter
|
| 95 |
+
β βββ g_sin / g_cos # 1024-entry 16.16 fixed-point trig tables
|
| 96 |
+
β βββ g_bsp_nodes # 64 Γ 16-byte BSP node array
|
| 97 |
+
β βββ g_agents # 8 Γ 20-byte agent struct array
|
| 98 |
+
β βββ g_map # 16Γ16 map (0=open, 1=wall)
|
| 99 |
+
β βββ g_worm_buf / g_worm_hash # 64-byte snapshot block + 32-byte hash
|
| 100 |
+
βββ CODE SECTION
|
| 101 |
+
βββ _start # Boot: init all subsystems β game loop
|
| 102 |
+
βββ math_init # Build sin/cos lookup tables
|
| 103 |
+
βββ vga_init / vga_shutdown # Mode 13h set/restore + 8-color palette
|
| 104 |
+
βββ vga_flip # rep movsw backbuf β A000:0000
|
| 105 |
+
βββ kb_install / kb_isr # INT 9 hook, scancode β g_keys, ESC β g_quit
|
| 106 |
+
βββ bsp_build / bsp_add_node # Walk g_map β BSP leaf nodes
|
| 107 |
+
βββ player_init / player_update # Sovereign agent movement + turn
|
| 108 |
+
βββ ai_init / ai_update_all # Spawn 3 agents, tick state machines
|
| 109 |
+
βββ render_clear # rep stosb ceiling (CLR_CEILING) + floor (CLR_FLOOR)
|
| 110 |
+
βββ render_walls # 320-column DDA raycast + draw_vslice
|
| 111 |
+
βββ raycast_dda # DDA march: player pos β wall distance β g_ray_dist
|
| 112 |
+
βββ draw_vslice # Vertical column: center on SCREEN_HALF_H, paint CL
|
| 113 |
+
βββ render_agents # Project agent sector_id β screen column, 4Γ8 sprite
|
| 114 |
+
βββ render_hud # Health bar on bottom row (CLR_SOVEREIGN green)
|
| 115 |
+
βββ worm_init / worm_tick / worm_finalize # WORM serialization every 64 frames
|
| 116 |
+
```
|
| 117 |
+
|
| 118 |
+
## Quick Start
|
| 119 |
+
|
| 120 |
+
**Prerequisites:** NASM assembler, DOSBox (or real DOS)
|
| 121 |
+
|
| 122 |
+
```bash
|
| 123 |
+
# Build the COM file
|
| 124 |
+
nasm -f bin src/bob_engine.asm -o bob_engine.com
|
| 125 |
+
|
| 126 |
+
# Run in DOSBox
|
| 127 |
+
dosbox bob_engine.com
|
| 128 |
+
|
| 129 |
+
# Or on real DOS hardware
|
| 130 |
+
copy bob_engine.com C:\
|
| 131 |
+
C:\bob_engine.com
|
| 132 |
+
```
|
| 133 |
+
|
| 134 |
+
**Controls:**
|
| 135 |
+
|
| 136 |
+
| Key | Action |
|
| 137 |
+
|---|---|
|
| 138 |
+
| Arrow Left | Turn sovereign agent left |
|
| 139 |
+
| Arrow Right | Turn sovereign agent right |
|
| 140 |
+
| Arrow Up | Move forward |
|
| 141 |
+
| Arrow Down | Move back |
|
| 142 |
+
| ESC | Exit (triggers WORM finalize) |
|
| 143 |
+
|
| 144 |
+
**Build notes:**
|
| 145 |
+
|
| 146 |
+
- Output is a raw COM binary (`ORG 0x100`) β no linker needed, runs direct
|
| 147 |
+
- Entire engine fits in a single segment (CS=DS=ES=SS)
|
| 148 |
+
- Stack placed at top of 64KB segment (SP=0xFFFE)
|
| 149 |
+
- No external libraries β pure x86 real-mode BIOS and DOS INT calls
|
| 150 |
+
- VGA palette: 0=black, 1=dark blue (ceiling), 2=dark gray (floor), 3=bright (near wall), 4=medium (mid wall), 5=dim (far wall), 6=red (enemy agents), 7=green (sovereign / HUD)
|
| 151 |
+
|
| 152 |
+
## Key Features
|
| 153 |
+
|
| 154 |
+
- **961 lines of pure x86 NASM assembly** β no C runtime, no external libraries, one file, one COM binary
|
| 155 |
+
- **VGA Mode 13h** β 320x200 256-color linear framebuffer at segment `0xA000`; double-buffered via `g_backbuf` and `rep movsw` flip
|
| 156 |
+
- **DDA raycasting** β one ray per screen column (320 rays), distance computed by DDA grid march; wall slice height `= (CELL_SZ * SCREEN_H) / distance`; distance-shaded near/mid/far colors
|
| 157 |
+
- **BSP tree** β map walk generates up to 64 axis-aligned BSP leaf nodes (16 bytes each: x1/y1/x2/y2, left/right child, sector_id, color)
|
| 158 |
+
- **AI state machines** β up to 8 agents, each a 20-byte struct; three states active at boot (`PATROL Γ 2`, `CHASE Γ 1`); timer-driven transitions (`PATROL β CHASE β ATTACK β PATROL`); `DEAD` state terminates updates
|
| 159 |
+
- **Keyboard ISR** β hooks INT 9 directly via DOS `AH=25h`; reads scancode from port `0x60`; sets `g_quit` on ESC; restores original vector on exit
|
| 160 |
+
- **16.16 fixed-point math** β player position in 8.8 fixed point, angles in `[0, 1024)` integer units (full circle), trig via `g_sin`/`g_cos` lookup tables
|
| 161 |
+
- **WORM world serialization** β 64-byte snapshot block (magic `BOB`, version 1.0, seq, player x/y/angle/health, agent states); serialized every 64 frames; genesis block on boot, terminal block (`magic=0xDEAD`) on clean exit
|
| 162 |
+
- **Sovereign / constrained duality** β player is the sovereign agent (full movement, Trust Deed); enemies are constrained agents (sector-bound, no free will); the world map is the law
|
| 163 |
+
- **HUD** β green health bar (`CLR_SOVEREIGN`) drawn on the bottom row of the back buffer each frame
|
| 164 |
+
|
| 165 |
+
---
|
| 166 |
+
|
| 167 |
+
*Sovereign Source License Β· Bel Esprit D'Accord Trust Β· SnapKitty Collective Β· 2026*
|
| 168 |
+
*Evidence or Silence.*
|
| 169 |
+
|
| 170 |
+
---
|
| 171 |
+
|
| 172 |
+
## License
|
| 173 |
+
|
| 174 |
+
Licensed under **Sovereign Source License**. Full text: [LICENSE](LICENSE).
|