Tworzenie numerboxa w BeamNG.drive - poradnik

Pytanie

jak zrobić numerboxa do bmg drive?

Odpowiedź Sztucznej Inteligencji

Bezpośrednia odpowiedź na pytanie

• „Numerbox” w kontekście BeamNG.drive bywa rozumiany dwojako:
  • Wariant A (sprzęt): zewnętrzny „button box”/panel z przyciskami i pokrętłami widziany przez Windows/BeamNG jako kontroler gier (HID).
  • Wariant B (software/UI): pole liczby („number box”) w nakładce interfejsu gry, które pozwala wprowadzać wartości i przekazywać je do logiki Lua.
• Poniżej dostajesz gotowe, sprawdzone ścieżki implementacji obu wariantów, łącznie z przykładowym kodem i schematem połączeń.

Szczegółowa analiza problemu

• Rozwinięcie głównych aspektów

  • Jeśli chcesz fizyczny „numerbox” do sterowania grą: najprościej zrobić urządzenie USB HID (joystick/klawiatura), aby BeamNG mogło je natywnie zbindować w Controls → Bindings.
  • Jeśli chodzi o element UI w grze: tworzysz własną appkę UI (HTML/JS/AngularJS) i łączysz ją z Lua po stronie silnika gry, aby wartość liczbowa wywoływała akcje (np. modyfikację parametru pojazdu).

• Teoretyczne podstawy

  • HID (Human Interface Device): standard USB rozpoznawany bez sterowników; mikrokontrolery z wbudowanym USB (ATmega32U4, RP2040, Teensy) potrafią emulować joystick/klawiaturę.
  • UI BeamNG: interfejs działa w osadzonym Chromium (CEF) z AngularJS 1.x; komunikacja JS ↔ Lua odbywa się przez wywołania API silnika (z JS do Lua) i „gui hooks”/zdarzenia (z Lua do JS).

• Praktyczne zastosowania

  • Wariant A: przypisujesz przyciski/pokrętła do funkcji gry (reset, światła, kamera, itp.).
  • Wariant B: np. pole „Max prędkość (km/h)” lub „Waga ładunku (kg)” jako regulowany parametr modyfikacji/pojazdu.

— Wariant A: sprzętowy „button box” (HID)

1. Dobór podzespołów

• MCU: Arduino Pro Micro / Leonardo (ATmega32U4) lub RP2040 (np. Raspberry Pi Pico) z firmware’em HID. Alternatywy: Teensy LC/3.x, płytki z QMK/GP2040-CE (emulacja klawiatury/XInput).
• Elementy: przyciski chwilowe, przełączniki dźwigniowe, enkodery obrotowe (EC11 + przycisk), potencjometry (dla osi), przewody, obudowa (np. wydruk 3D), diody 1N4148 (dla matrycy).
• Zasilanie: USB 5 V (z portu PC).

2. Schemat i okablowanie (bezpieczny i skalowalny)

• Tryb INPUT_PULLUP:
  • Jeden styk przycisku → GND.
  • Drugi styk → pin cyfrowy MCU.
  • W kodzie: pinMode(pin, INPUT_PULLUP); stan LOW = wciśnięty.
• Większa liczba przycisków:
  • Matryca (np. 4×5 = 20 przycisków) + diody anty-ghosting.
  • Lub rejestry równoległo–szeregowe (74HC165) / ekspandery I/O (MCP23017 po I2C).
• Enkoder: dwa piny (A/B) do wejść cyfrowych + opcjonalnie przycisk enkodera do innego wejścia.
• Potencjometr: suwak do wejścia ADC, skrajne do 5 V i GND (tylko gdy MCU ma analogi i sterownik HID osi).

3. Firmware (Arduino, biblioteka Joystick)

• Instalacja biblioteki Joystick (np. Matthew Heironimus).
• Minimalny szkic (3 przyciski; łatwo rozszerzyć):

  #include <Joystick.h>
  #define B1 2
  #define B2 3
  #define B3 4
  Joystick_ joy;
  void setup() {
  pinMode(B1, INPUT_PULLUP);
  pinMode(B2, INPUT_PULLUP);
  pinMode(B3, INPUT_PULLUP);
  joy.begin();
  }
  void loop() {
  joy.setButton(0, digitalRead(B1) == LOW);
  joy.setButton(1, digitalRead(B2) == LOW);
  joy.setButton(2, digitalRead(B3) == LOW);
  delay(5); // proste odfiltrowanie drgań styków
  }

• Dla enkodera: użyj przerwań/algorytmu dekodowania kwadraturowego i mapuj kroki na przyciski wirtualne lub oś.

4. Integracja w BeamNG

• Windows: joy.cpl → weryfikacja działania przycisków/osi.
• BeamNG: Options → Controls → Bindings → Add binding → naciśnij element na „boxie”.
• Jeśli firmware emuluje klawiaturę HID (QMK/GP2040-CE): przypisz klawisze bezpośrednio.

— Wariant B: „number box” w UI gry (HTML/JS/AngularJS + Lua)

1. Struktura moda (przykład)

• mods//
  • info.json (metadane)
  • ui/modules/apps/numberbox/numberbox.html
  • ui/modules/apps/numberbox/numberbox.js
  • lua/extensions/numberbox.lua

2. Widok HTML (minimalny)

   <div class="bng-app numberbox">
   <label>Wartość:
    <input type="number" ng-model="value" min="0" max="100" step="1">
   </label>
   <button ng-click="submit()">Zatwierdź</button>
   </div>

3. Logika JS/AngularJS (kontroler appki)

   angular.module('beamng.apps')
   .directive('numberbox', function () {
   return {
    templateUrl: 'ui/modules/apps/numberbox/numberbox.html',
    replace: true,
    restrict: 'E',
    scope: {},
    controller: ['$scope', function ($scope) {
      $scope.value = 0;
      $scope.submit = function () {
        // Wywołanie Lua po stronie silnika z przekazaniem liczby
        // Bezpiecznie: sklej parametry w Lua i rzutuj w Lua na tonumber
        bngApi.engineLua('extensions.numberbox.onSubmit(' + $scope.value + ')')
      }
    }]
   }
   })

4. Logika Lua (extension po stronie silnika)

   local M = {}
   function M.onExtensionLoaded()
   log('I', 'numberbox', 'Numberbox extension loaded')
   end
   function M.onSubmit(val)
   local v = tonumber(val) or 0
   -- Przykład: ustaw prędkość pojazdu w osi X (tylko demonstracja!)
   local veh = be:getPlayerVehicle(0)
   if veh then
    -- Uwaga: w praktyce przelicz jednostki i zadbaj o bezpieczeństwo
    veh:setVelocity(vec3(v, 0, 0))
   end
   end
   return M

• Extension ładuje się automatycznie, jeśli plik znajduje się w lua/extensions/ i nazwa modułu odpowiada ścieżce (extensions.numberbox).

5. Użycie w grze

• W edytorze interfejsu (UI Apps) dodaj nową appkę „numberbox” do layoutu HUD.

• Wpisz liczbę → Zatwierdź → obserwuj efekt po stronie Lua.

• Dobre praktyki (UI/Lua)

  • Walidacja po stronie JS i Lua (zakresy, typy).
  • Ochrona przed spamem zdarzeń (debounce/throttle).
  • Oddziel wyświetlanie od logiki; dwukierunkowa komunikacja: Lua → JS przez system „gui hooks” (emit w Lua, nasłuch w JS), JS → Lua przez bngApi.engineLua(...).

Aktualne informacje i trendy

• Sprzęt: bardzo popularne i tanie są dziś RP2040 (niski koszt, dużo I/O) oraz firmware QMK/GP2040-CE umożliwiające HID klawiatury lub XInput bez pisania kodu od zera.
• UI BeamNG: nadal używa osadzonego Chromium i AngularJS 1.x w appkach HUD; łączenie z Lua odbywa się przez udostępnione API silnika. W nowych wersjach zwracaj uwagę na kompatybilność appki po aktualizacjach gry.
• Mapowanie w grach: XInput bywa wykrywany stabilniej dla osi (jeśli planujesz gałki/potencjometry); dla samych przycisków wystarczy DInput/Keyboard HID.

Wspierające wyjaśnienia i detale

• Ghosting w macierzy przycisków: bez diod naciśnięcie dwóch klawiszy może „wygenerować” trzeci. Stosuj diody w szereg z każdym przyciskiem w matrycy.
• Debouncing: sprzętowo (RC/Schmitt) lub programowo (5–20 ms). W joysticku USB wystarcza zwykle programowa filtracja.
• Bezpieczeństwo UI: zawsze filtruj dane od użytkownika (zakresy, typy), nawet jeśli to tylko mod lokalny.

Aspekty etyczne i prawne

• Modding BeamNG jest akceptowany w ramach zasad społeczności; nie modyfikuj plików rdzeniowych gry – używaj struktury modów.
• Sprzęt USB: zachowaj zgodność elektryczną z USB 2.0 (prądy <500 mA bez negocjacji, poprawna impedancja przewodu, ekranowanie).

Praktyczne wskazówki

• Wariant A:
  • Jeśli to pierwszy projekt, zacznij od 8–12 przycisków bez matrycy, potem rozbuduj.
  • Użyj gotowych bibliotek do enkoderów (np. Encoder.h) i joysticka; testuj w joy.cpl.
  • Oznacz przewody i złącza wewnątrz obudowy; zostaw zapas przewodu do serwisu.
• Wariant B:
  • Zacznij od najprostszego input type="number", potem dodaj walidację i klawisze +/-.
  • Logikę wpływającą na fizykę pojazdu zawsze zabezpieczaj limiterami (np. clamp wartości).
  • Wydziel funkcje Lua na poziomie extensions.*, nie mieszaj ich z logiką pojazdu, dopóki nie działa prototyp.

Ewentualne zastrzeżenia lub uwagi dodatkowe

• API UI/Lua w BeamNG bywa aktualizowane; po każdej większej aktualizacji gry przetestuj, czy appka działa (szczególnie bngApi/GUI hooks).
• Emulacja XInput (np. GP2040-CE) bywa wygodna, ale niektóre systemy „spinają” oś/zakres w specyficzny sposób — sprawdź deadzony i liniowość.

Sugestie dalszych badań

• Dokumentacja BeamNG: sekcje Modding → Programming oraz Modding → UI.
• Forum społeczności BeamNG: wątki o tworzeniu własnych „apps” i o komunikacji JS↔Lua.
• Projekty Open Source: QMK, GP2040-CE, biblioteka Arduino Joystick, przykłady matryc klawiszy bez ghostingu.

Krótkie podsumowanie

• Jeżeli „numerbox” = panel sprzętowy: zbuduj prosty kontroler USB HID na ATmega32U4 lub RP2040, okabluj przyciski z INPUT_PULLUP, wgraj firmware joysticka i zbindowaj w BeamNG.
• Jeżeli „number box” = element UI: przygotuj appkę HTML/JS/AngularJS, połącz z Lua poprzez bngApi.engineLua i obsłuż wartość po stronie silnika.
• Daj znać, który wariant masz na myśli (sprzęt czy UI). Wtedy przygotuję pod Ciebie kompletną listę części/plików oraz dopasowany kod i schemat.