README.it.md

[ English | 中文 | Deutsch | Español | Français | Italiano | 日本語 | 한국어 | Português | Русский | Türkçe | Українська ]

Pyxel è un game engine rétro per Python.

Grazie alle sue specifiche limitate ispirate dalle console di videogiochi rétro, come al fatto che solo 16 colori possono essere mostrati e solo 4 suoni possono essere riprodotti allo stesso tempo, puoi sentirti libero di creare giochi stile pixel art.

La motivazione dello sviluppo di Pyxel è il feedback degli utenti. Date a Pyxel una stella su GitHub!

Le specifiche e le API di Pyxel sono ispirate da PICO-8 e TIC-80.

Pyxel è open source sotto la licenza MIT e può essere utilizzato liberamente. Cominciamo a fare giochi rétro con Pyxel!

Specifiche

• Funziona su Windows, Mac, Linux e Web
• Programmazione in Python
• Tavolozza di 16 colori
• 3 banchi di immagini di dimensioni 256x256
• 8 mappe di tile di dimensioni 256x256
• 4 canali con 64 suoni definibili
• 8 tracce musicali che possono combinare qualsiasi suono
• Input da tastiera, mouse e gamepad
• Editor di immagini e suoni
• Espansione di colori, canali e banchi da parte dell'utente

Palette colori

Come installare

Windows

Dopo aver installato Python3 (versione 3.8 o superiore), eseguire il seguente comando:

pip install -U pyxel

Se si installa Python utilizzando il programma di installazione ufficiale, selezionare la casella di controllo Add Python 3.x to PATH per abilitare il comando pyxel.

Mac

Dopo aver installato Homebrew, eseguire i comandi seguenti:

brew install pipx
pipx ensurepath
pipx install pyxel

Per aggiornare la versione dopo l'installazione di Pyxel, eseguire pipx upgrade pyxel.

Linux

Dopo aver installato il pacchetto SDL2 (libsdl2-dev per Ubuntu), Python3 (versione 3.8 o superiore), e python3-pip, eseguire il seguente comando:

sudo pip3 install -U pyxel

Se quanto sopra non funziona, provare ad autocostruirsi secondo le istruzioni di Makefile.

Web

La versione web di Pyxel non richiede l'installazione di Python o Pyxel e funziona su PC, smartphone e tablet con browser web supportati.

Per istruzioni specifiche, consultare questa pagina.

Provare gli esempi di Pyxel

Dopo aver installato Pyxel, gli esempi di Pyxel saranno copiati nella corrente cartella con il comando seguente:

pyxel copy_examples

Gli esempi da copiare sono i seguenti:

01_hello_pyxel.py	Applicazione più semplice	Demo	Code
02_jump_game.py	Un gioco di salto con file Pyxel di risorsa	Demo	Code
03_draw_api.py	Dimostrazione delle API di disegno	Demo	Code
04_sound_api.py	Dimostrazione delle API del suono	Demo	Code
05_color_palette.py	Lista di colori nella palette	Demo	Code
06_click_game.py	Gioco punta e clicca	Demo	Code
07_snake.py	Gioco snake con colonna sonora	Demo	Code
08_triangle_api.py	Dimostrazione delle API per il disegno di un triangolo	Demo	Code
09_shooter.py	Gioco shoot'em up con transizioni schermo	Demo	Code
10_platformer.py	Gioco a piattaforme a scorrimento orizzontale con mappa	Demo	Code
11_offscreen.py	Renderizzazione fuori campo con la classe Image	Demo	Code
12_perlin_noise.py	Animazione del rumore di Perlin	Demo	Code
13_bitmap_font.py	Disegno di un font bitmap	Demo	Code
14_synthesizer.py	Sintetizzatore che utilizza funzioni di espansione audio	Demo	Code
15_tiled_map_file.py	Caricamento e disegno di un file di mappa di piastrelle (.tmx)	Demo	Code
16_transform.py	Rotazione e scalatura dell'immagine	Demo	Code
99_flip_animation.py	Animazione con funzione flip (solo per piattaforme non web)	Demo	Code
30sec_of_daylight.pyxapp	Gioco vincitore del primo Pyxel Jam sviluppato da Adam	Demo	Code
megaball.pyxapp	Gioco arcade di palla basato sulla fisica sviluppato da Adam	Demo	Code
8bit-bgm-gen.pyxapp	Generatore di musica di sottofondo realizzato da frenchbread	Demo	Code

Un esempio può essere eseguito con i seguenti comandi:

cd pyxel_examples
pyxel run 01_hello_pyxel.py
pyxel play 30sec_of_daylight.pyxapp

Come usare

Creare una applicazione Pyxel

Dopo aver importato il modulo Pyxel nel tuo script Python, prima specifica la dimensione della finestra con la funzione init, dopodichè lancia l'applicazione Pyxel con la funzione run.

import pyxel

pyxel.init(160, 120)

def update():
    if pyxel.btnp(pyxel.KEY_Q):
        pyxel.quit()

def draw():
    pyxel.cls(0)
    pyxel.rect(10, 10, 20, 20, 11)

pyxel.run(update, draw)

I parametri della funzione run sono passati alla funzione update per aggiornare ogni frame e alla funzione draw per disegnare lo schermo quando necessario.

In un'applicazione reale, è consigliato includere il codice Pyxel in una classe come qui sotto:

import pyxel

class App:
    def __init__(self):
        pyxel.init(160, 120)
        self.x = 0
        pyxel.run(self.update, self.draw)

    def update(self):
        self.x = (self.x + 1) % pyxel.width

    def draw(self):
        pyxel.cls(0)
        pyxel.rect(self.x, 0, 8, 8, 9)

App()

Quando si creano grafici semplici senza animazione, si può usare la funzione show per rendere il codice più conciso.

import pyxel

pyxel.init(120, 120)
pyxel.cls(1)
pyxel.circb(60, 60, 40, 7)
pyxel.show()

Eseguire applicazioni Pyxel

Uno script Python creato può essere eseguito con il comando python:

python PYTHON_SCRIPT_FILE

Può anche essere eseguito con il comando pyxel run:

pyxel run PYTHON_SCRIPT_FILE

Inoltre, il comando pyxel watch consente di monitorare i cambiamenti in una directory specificata, eseguendo automaticamente il programma quando vengono rilevati cambiamenti:

pyxel watch WATCH_DIR PYTHON_SCRIPT_FILE

Il monitoraggio della directory può essere interrotto premendo Ctrl(Command)+C.

Controlli speciali

I controlli seguenti speciali possono essere eseguite mentre viene eseguita un'applicazione Pyxel:

• Esc
  Esci dall'applicazione
• Alt(Option)+1
  Salva uno screenshot sul desktop
• Alt(Option)+2
  Resetta il tempo d'inizio della registrazione schermo
• Alt(Option)+3
  Salva la registrazione schermo sul desktop (fino a 10 secondi)
• Alt(Option)+9
  Passare da una modalità all'altra (Crisp/Smooth/Retro)
• Alt(Option)+0
  Alterna il monitor di performance (fps, tempo d'aggiornamento, e tempo di disegno)
• Alt(Option)+Enter
  Alterna schermo intero
• Shift+Alt(Option)+1/2/3
  Salvare il banco di immagini corrispondente sul desktop
• Shift+Alt(Option)+0
  Salva la tavolozza dei colori corrente sul desktop

Come creare una risorsa

L'Editor Pyxel può creare immagini e suoni utilizzati in un'applicazione Pyxel.

Si avvia con il seguente comando:

pyxel edit PYXEL_RESOURCE_FILE

Se il file di risorsa Pyxel (.pyxres) specificato esiste, allora il file viene caricato, e se non esiste, un nuovo file con quel nome viene creato. Se il file risorsa viene omesso, il nome è my_resource.pyxres.

Dopo aver avviato l'Editor Pyxel, il file può essere scambiato trascinando e rilasciando un altro file risorsa.

Il file risorsa creato può essere caricato con la funzione load.

L'editor Pyxel ha le seguenti modalità di modifica.

Editor Immagini

La modalità per modificare banche d'immagini.

Trascinare e rilasciare un file immagine (PNG/GIF/JPEG) nell'Editor immagini per caricare l'immagine nel banco immagini attualmente selezionato.

Editor Tilemap

La modalità per modificare tilemap immagini delle banche immagini sono posizionate in un modo a piastrelle.

Trascinare e rilasciare un file TMX (Tiled Map File) nel Tilemap Editor per caricare il suo layer nell'ordine di disegno corrispondente al numero di tilemap attualmente selezionato.

Editor Suoni

Modalità per modificare suoni.

Editor Musica

La modalità per modificare musica in cui i suoni sono posizionati in ordine per poi essere risuonati.

Altri metodi per creare risorse

Le immagini e le tilemap Pyxel possono essere create mediante i seguenti metodi:

• Creare un'immagine da una lista di stringhe con la funzione Image.set o la funzione Tilemap.set
• Caricare un file immagine (PNG/GIF/JPEG) nella palette di Pyxel con la funzione Image.load

I suoni Pyxel possono anche essere creati nel modo seguente:

• Creare un suono con le stringhe con la funzione Sound.set o la funzione Music.set

Riferirsi al manuale dell'API per l'uso di queste funzioni.

Come distribuire l'applicazione

Pyxel supporta un formato file dedicato per la distribuzione dell'applicazione (Pyxel application file) che funziona su tutte le piattaforme.

Creare il file dell'applicazione Pyxel (.pyxapp) con il comando pyxel package:

pyxel package APP_DIR STARTUP_SCRIPT_FILE

Se l'applicazione deve includere risorse o moduli aggiuntivi, collocarli nella directory dell'applicazione.

I metadati possono essere visualizzati in fase di esecuzione specificandoli nel seguente formato all'interno dello script di avvio. I campi diversi da title e author possono essere omessi.

# title: Pyxel Platformer
# author: Takashi Kitao
# desc: A Pyxel platformer example
# site: https://github.com/kitao/pyxel
# license: MIT
# version: 1.0

Il file di applicazione creato può essere eseguito con il comando pyxel play:

pyxel play PYXEL_APP_FILE

Il file di applicazione Pyxel può anche essere convertito in un file eseguibile o in un file HTML con i comandi pyxel app2exe o pyxel app2html.

Manuale API

Sistema

• width, height
  Lunghezza e altezza dello schermo

• frame_count
  Numero di frame passati

• init(width, height, [title], [fps], [quit_key], [display_scale], [capture_scale], [capture_sec])
  Inizializza l'applicazione Pyxel con la dimensione dello schermo (width, height). I seguenti possono essere specificati come opzioni: il titolo della finestra con title, il frame rate con fps, il pulsante per uscire dall'applicazione con quit_key, la scala del display con display_scale, la scala della cattura dello schermo con capture_scale, ed il tempo di registrazione massimo del video di cattura dello schermo con capture_sec.
  e.g. pyxel.init(160, 120, title="My Pyxel App", fps=60, quit_key=pyxel.KEY_NONE, capture_scale=3, capture_sec=0)

• run(update, draw)
  Avvia l'applicazione Pyxel e chiama la funzione update per l'aggiornamento del frame e la funzione draw per disegnare.

• show()
  Mostra lo schermo e attende fino a quando il pulsante Esc non viene premuto.

• flip()
  Riavvolge lo schermo di un fotogramma. L'applicazione esce quando viene premuto il tasto Esc. Questa funzione non funziona nella versione web.

• quit()
  Esci dall'applicazione Pyxel.

Risorse

• load(filename, [excl_images], [excl_tilemaps], [excl_sounds], [excl_musics])
  Carica il file risorsa (.pyxres). Se un'opzione è True, la risorsa non verrà caricata. Se esiste un file di tavolozza (.pyxpal) con lo stesso nome nella stessa posizione del file di risorsa, anche il colore di visualizzazione della tavolozza verrà modificato. Il file della tavolozza è una voce esadecimale dei colori di visualizzazione (ad esempio, 1100FF), separata da newline. Il file della tavolozza può essere usato anche per cambiare i colori visualizzati nell'Editor Pyxel.

Input

• mouse_x, mouse_y
  La posizione corrente del cursore del mouse

• mouse_wheel
  Il valore corrente della rotella del mouse

• btn(key)
  Ritorna True se key è premuto, altrimenti ritorna False. (lista definizione tasti)

• btnp(key, [hold], [repeat])
  Ritorna True se key è premuto quel frame, altrimenti ritorna False. Quando hold e repeat sono specificati, True sarà ritornato all'intervallo frame repeat quando key è premuto per più di hold frame.

• btnr(key)
  Ritorna True se key è rilasciato quel frame, altrimenti ritorna False

• mouse(visible)
  Se visible è True, mostra il cursore mouse. Se False, nascondilo. Anche se il cursore mouse non è mostrato, la sua posizione è aggiornata.

Grafica

• colors
  Lista della palette colori del display. Il colore del display è specificato tramite un valore numerico a 24-bit. Usare colors.from_list e colors.to_list per assegnare direttamente e recuperare le liste Python.
  e.g. old_colors = pyxel.colors.to_list(); pyxel.colors.from_list([0x111111, 0x222222, 0x333333]); pyxel.colors[15] = 0x112233

• images
  Elenco dei banchi immagine (0-2). (Vedere la classe Image)
  e.g. pyxel.images[0].load(0, 0, "title.png")

• tilemaps
  Elenco delle tilemaps (0-7). (Vedere la classe Tilemap)

• clip(x, y, w, h)
  Imposta l'area di disegno dello schermo da (x, y) a lunghezza w e altezza h. Resettare l'area di disegno a schermo intero con clip()

• camera(x, y)
  Cambia le coordinate dell'angolo superiore sinistro dello schermo in (x, y). Resetta le coordinate dell'angolo superiore sinistro a (0, 0) con camera().

• pal(col1, col2)
  Rimpiazza colore col1 con col2 al momento di disegno. pal() per tornare alla palette iniziale.

• dither(alpha)
  Applica il dithering (pseudo-trasparenza) al disegno. Impostare alpha nell'intervallo 0,0-1,0, dove 0,0 è trasparente e 1,0 è opaco.

• cls(col)
  Riempie lo schermo con col

• pget(x, y)
  Ritorna il colore del pixel su (x, y).

• pset(x, y, col)
  Disegna un pixel di colore col su (x, y).

• line(x1, y1, x2, y2, col)
  Disegna una linea di colore col da (x1, y1) a (x2, y2).

• rect(x, y, w, h, col)
  Disegna un rettangolo con lunghezza w, altezza h e colore col da (x, y).

• rectb(x, y, w, h, col)
  Disegna il contorno di un rettangolo di lunghezza w, altezza h e colore col da (x, y).

• circ(x, y, r, col)
  Disegna un cerchio di raggio r e colore col su (x, y).

• circb(x, y, r, col)
  Disegna il contorno di un cerchio di raggio r e colore col su (x, y).

• elli(x, y, w, h, col)
  Disegna un'ellisse di larghezza w, altezza h e colore col da (x, y).

• ellib(x, y, w, h, col)
  Disegna il contorno di un'ellisse di larghezza w, altezza h e colore col da (x, y).

• tri(x1, y1, x2, y2, x3, y3, col)
  Disegna un triangolo con vertici (x1, y1), (x2, y2), (x3, y3) e colore col

• trib(x1, y1, x2, y2, x3, y3, col)
  Disegna il contorno di un triangolo con vertici (x1, y1), (x2, y2), (x3, y3) e colore col

• fill(x, y, col)
  Disegna un'ellisse di larghezza w, altezza h e colore col da (x, y).

• blt(x, y, img, u, v, w, h, [colkey], [rotate], [scale])
  Copia la regione di grandezza (w, h) da (u, v) della banca immagini img(0-2) a (x, y). Se un valore negativo è impostato per w e/o h, sarà invertito orizzontalmente o verticalmente. Se colkey è specificato, verrà trattato come colore trasparente. Se viene specificato rotate(in gradi), scale(1.0=100%) o entrambi, verrà applicata la trasformazione corrispondente.

• bltm(x, y, tm, u, v, w, h, [colkey], [rotate], [scale])
  Copia la regione di dimensione (w, h) da (u, v) della tilemap tm(0-7) a (x, y). Se un valore negativo è stato impostato per w e/o h, sarà rovesciata orizzontalmente e/o verticalmente. Se colkey è specificato, viene trattato come colore trasparente. Se viene specificato rotate(in gradi), scale(1.0=100%) o entrambi, verrà applicata la trasformazione corrispondente. La dimensione di una tile tile è di 8x8 pixel ed è memorizzata in una tilemap come una tupla di (tile_x, tile_y).

• text(x, y, s, col)
  Disegna una stringa s di colore col su (x, y).

Audio

• sounds
  Elenco dei suoni (0-63). (Vedere classe Sound)
  per esempio: pyxel.sounds[0].speed = 60

• musics
  Elenco delle musiche (0-7). (Vedere la classe Music)

• play(ch, snd, [tick], [loop], [resume])
  Riproduce il suono snd(0-63) sul canale ch(0-3). Se snd è una lista, verrà riprodotta in ordine. La posizione di inizio della riproduzione può essere specificata da tick(1 tick = 1/120 secondi). Se True è specificato per loop, viene eseguita la riproduzione in loop. Per riprendere il suono precedente dopo la fine della riproduzione, impostare resume su True.

• playm(msc, [tick], [loop])
  Riproduce la musica msc(0-7). La posizione di inizio della riproduzione può essere specificata da tick(1 tick = 1/120 secondi). Se True è specificato per loop, viene eseguita la riproduzione in loop.

• stop([ch])
  Interrompe la riproduzione del canale ch(0-3) specificato. stop() per interrompere tutti i canali.

• play_pos(ch)
  Ottiene la posizione del suono in riproduzione del canale ch(0-3) come una tupla di (sound_no, note_no). Ritorna None quando la riproduzione è interrotta.

Matematica

• ceil(x)
  Restituisce il più piccolo intero maggiore o uguale a x.

• floor(x)
  Restituisce il più grande intero minore o uguale a x.

• sgn(x)
  Restituisce 1 quando x è positivo, 0 quando è 0 e -1 quando è negativo.

• sqrt(x)
  Restituisce la radice quadrata di x.

• sin(deg)
  Restituisce il seno di deg gradi.

• cos(deg)
  Restituisce il coseno di deg gradi.

• atan2(y, x)
  Restituisce l'arcotangente di y/x in gradi.

• rseed(seed)
  Imposta il seme del generatore di numeri casuali.

• rndi(a, b)
  Restituisce un numero intero casuale maggiore o uguale a a e minore o uguale a b.

• rndf(a, b)
  Restituisce un decimale casuale maggiore o uguale a a e minore o uguale a b.

• nseed(seed)
  Imposta il seme del rumore di Perlin.

• noise(x, [y], [z])
  Restituisce il valore del rumore di Perlin per le coordinate specificate.

Image Class

• width, height
  La lunghezza e l'altezza dell'immagine

• set(x, y, data)
  Imposta l'immagine a (x, y) tramite una lista di stringhe.
  e.g. pyxel.images[0].set(10, 10, ["0123", "4567", "89ab", "cdef"])

• load(x, y, filename)
  Carica il file immagine (PNG/GIF/JPEG) in (x, y).

• pget(x, y)
  Ritorna il colore del pixel su (x, y).

• pset(x, y, col)
  Disegna un pixel di colore col su (x, y).

Classe Tilemap

• width, height
  Lunghezza e altezza della tilemap

• imgsrc
  Il banco immagine (0-2) referenziato dalla tilemap

• set(x, y, data)
  Imposta la tilemap a (x, y) mediante una lista di stringhe.
  e.g. pyxel.tilemap(0).set(0, 0, ["0000 0100 a0b0", "0001 0101 a1b1"])

• load(x, y, filename, layer)
  Caricare il layer nell'ordine di disegno layer(0-) dal file TMX (Tiled Map File) a (x, y).

• pget(x, y)
  Prende la tile in (x, y). Una tile è una tupla di (tile_x, tile_y).

• pset(x, y, tile)
  Disegna una tile in (x, y). Una tile è una tupla di (tile_x, tile_y).

Classe Sound

• notes
  Lista di note (0-127). Più alto il numero, più alto il tono, e a 33 diventa 'A2'(440Hz). Il resto è -1.

• tones
  Lista di tonalità (0:Triangolo / 1:Quadrato / 2:Ritmo / 3:Rumore)

• volumes
  Lista di volumi (0-7)

• effects
  Lista di effetti (0:None / 1:Slide / 2:Vibrato / 3:FadeOut / 4:Half-FadeOut / 5:Quarter-FadeOut)

• speed
  Velocità di riproduzione. 1 è il più veloce, e più grande è il numero, più è lenta la velocità di riproduzione. A 120, la lunghezza di una nota diventa 1 secondo.

• set(notes, tones, volumes, effects, speed)
  Imposta note, tonalità, volumi, ed effetti con una stringa. Se il numero di tonalità, volumi, ed effetti è inferiore alle note, vengono ripetuti dall'inizio.

• set_notes(notes)
  Imposta le note con una stringa composta da 'CDEFGAB'+'#-'+'01234' o 'R'. Case-insensitive e gli spazi bianchi sono ignorati.
  e.g. pyxel.sounds[0].set_notes("G2B-2D3R RF3F3F3")

• set_tones(tones)
  Imposta le tonalità con una stringa formata da 'TSPN'. Case-insensitive e gli spazi bianchi sono ignorati.
  e.g. pyxel.sounds[0].set_tones("TTSS PPPN")

• set_volumes(volumes)
  Imposta i volumi con una stringa formata da '01234567'. Case-insensitive e gli spazi bianchi sono ignorati.
  e.g. pyxel.sounds[0].set_volumes("7777 7531")

• set_effects(effects)
  Imposta gli effetti con una stringa formata da 'NSVFHQ'. Case-insensitive e gli spazi bianchi sono ignorati.
  e.g. pyxel.sounds[0].set_effects("NFNF NVVS")

Music Class

• seqs
  Lista bidimensionale di suoni (0-63) con il numero di canali

• set(seq0, seq1, seq2, ...)
  Impostare gli elenchi di suoni (0-63) dei canali. Se è indicata una lista vuota, quel canale non viene utilizzato per la riproduzione.
  e.g. pyxel.musics[0].set([0, 1], [], [3])

Advanced APIs

Pyxel ha "API avanzate" che non sono menzionate in questa documentazione perchè "potrebbero confondere gli utenti" oppure "necessitano di conoscenze specifiche per poter essere utilizzate".

Se ti senti confidente sulle tue competenze, prova a creare lavori incredibili con this come idea!

Come contribuire

Inviare Issue

Usa l'Issue Tracker per inviare segnalazioni su bug e richieste di funzionalità/migliorie. Prima di inviare una nuova issue, assicurati che non ci sia una issue simile aperta.

Manual Testing

Chiunque è il benvenuto per testare manualmente il codice e riportare bug o suggerimenti per miglioramenti nell'Issue Tracker!

Submitting Pull Request

Patch/fix sono accettati in forma di pull request (PR). Assicurarsi che il problema per cui si emetta una pull request sia aperto nel tracciante di problemi.

La pull request inviata è considerata accettata per la pubblicazione sotto la Licenza MIT.

Altre informazioni

• FAQ
• Esempi di utenti
• Account dello sviluppatore X

Licenza

Pyxel è sotto Licenza MIT. Può essere riutilizzato all'interno di software proprietari, a condizione che tutte le copie del software o delle sue parti sostanziali includano una copia dei termini della Licenza MIT e anche un avviso di copyright.

Reclutare Sponsor

Pyxel è alla ricerca di sponsor su GitHub Sponsor. Prendi in considerazione la sponsorizzazione di Pyxel per la manutenzione continua e l'aggiunta di funzionalità. Gli sponsor possono consultare Pyxel come vantaggio. Si prega di vedere qui per i dettagli.