04 - Convenzioni e Disclaimer

3 min read

Convenzioni e Disclaimer

INFO

Questa nota definisce le regole di stile della guida e i limiti di accuratezza degli esempi. Leggila prima di usare il codice o gli XML in produzione.

Frontmatter e Publish

Le note della guida vengono pubblicate su publish.okanne.it tramite private-quartz-publish (Quartz). Ogni nota pubblicabile deve avere questo frontmatter:

---
slug: AbCdEfGhIj     # 10 caratteri alfanumerici univoci
publish: true        # true = pubblicata sul sito
folder_slug: yeS3dZMfr8
folder_name: Guide
folder_path: 01 - Preparazione Strumenti/05 - Struttura fxmanifest   # percorso modulo/nota senza .md
---

Regole:

  • slug 10 caratteri, univoco (genera uno nuovo se la nota viene duplicata)
  • folder_slug e folder_name sono fissi per tutta la cartella Guide (yeS3dZMfr8 / Guide)
  • folder_path è il percorso relativo dalla cartella Guide, senza estensione .md
  • publish: false se la nota è una bozza da non mostrare sul sito
  • Le note in cartelle esterne (es. Progetto ReawakeR) hanno folder_slug e folder_name propri

Accuratezza degli Schemi

XML .meta (weapons.meta, vehicles.meta, pedvariation.meta, shop_ped_apparel.meta, ecc.)

WARNING

Gli XML mostrati nelle guide sono schemi didattici semplificati, validi per capire il flusso di lavoro, non copie complete dei file vanilla GTA V.

  • I nomi dei campi (es. FLAG_* in vehicles.meta, <Name> in weaponlayouts) possono non combaciare 1:1 col formato reale del gioco
  • I formati binari (YMT, YDR, YMAP) non sono mai “XML” nel file finale: gli XML servono solo come rappresentazione didattica
  • Prima di pubblicare una risorsa, confronta sempre con il file vanilla estratto via OpenIV/CodeWalker o con la documentazione ufficiale

API Lua (ESX, ox_inventory, ox_target, ox_lib)

  • Gli esempi sono verificati contro la documentazione ufficiale ove possibile
  • Le API ox evolvono rapidamente: se un esempio non funziona, controlla il README del repository GitHub aggiornato
  • I link delle risorse ufficiali sono nella Risorse Utili

Anti-Pattern da Evitare

Questi errori compaiono in codice trovato online e non vanno replicati:

Anti-patternPerché è sbagliatoAlternativa
Loop while true con Wait(0) su operazioni pesantiBrucia il frame budget, causa lagWait(500)+ o event-driven
ox_target:addModel() dentro un while trueRegistra la stessa zona migliaia di volteChiamala una volta a risorsa start
Generare la targa due volte (GeneratePlateText)Duplica il valore, rompe il DBGenera una sola volta e salva
Mandare soldi al client e fidarsi del valore ricevutoChiunque può alterare il clientValidazione sempre lato server
RegisterNetEvent senza controlli sourceExploit di giocatori malevoliVerifica identità/autorizzazione

Stile delle Note

Ogni nota segue una struttura comune:

  1. Frontmatter publish
  2. > [!INFO] o > [!QUESTION] introduttivo
  3. Tabella Obiettivo | Dettagli con cosa imparerai e prerequisiti
  4. Contenuto con sezioni ##
  5. Box > [!WARNING]/> [!TIP]/> [!NOTE] per avvertimenti
  6. Checklist finale dove utile
  7. Link “Prossimo passo” o “Torna alla Indice Generale”

Callout Obsidian: [!INFO], [!TIP], [!WARNING], [!QUESTION], [!NOTE]. Evita emoji fuori posto e caratteri non-ASCII accidentali.

Test Prima di Pubblicare

  • Tutti i wikilink puntano a note esistenti
  • Frontmatter completo e slug univoco
  • Niente API inventate o campi XML non verificati
  • Niente anti-pattern
  • Esempi di codice validi Lua/XML
  • Publish true solo per note complete

Torna alla: Indice Generale