📦 Jak stworzyć paczkę na Craftserve Dodatki?

Uwaga: Tworzenie projektów i wersji wymaga zakupionej usługi. Zakup usługę już na teraz na craftserve.com

Oto propozycja przejrzystego i estetycznego spisu treści w stylu dokumentacji technicznej, który możesz dodać na początek dokumentu (np. zaraz pod tytułem):

📚 Spis treści

🔧 Tworzenie nowego projektu
📦 Tworzenie wersji
🧪 Opcje zaawansowane
- 3.1 🧩 Niestandardowe zależności i tagi
- 3.2 🏷️ Etykiety i manifest paczki

Tworzenie projektu 🔨

Aby Twój projekt był możliwy do pobrania, oraz aby użytkownicy mogli go zobaczyć w galerii dodatków należy najpierw utworzyć nowy projekt.

Wejdź do panelu zarządzania serwerem, następnie w Galerie Dodatków, oraz kliknij odnośnik “Utwórz projekt”

W kreatorze projektu wypełnij poszczególne pola
Nazwa projektu – Wyświetla się w marketplace, oraz dzięki temu polu użytkownicy będą mogli wyszukiwać Twój projekt po nazwie.
Skrót - te pole wypełnia się automatycznie względem nazwy którą wypełnisz, odpowiada ono za identyfikacje projektu w linku.
Krótki opis – Pojawia się po kliknięciu w projekt nad przyciskiem "Zagraj teraz" lub "Zainstaluj najnowszą wersję" (w zależności od typu projektu). Wyświetla się również w kafelku w liście zainstalowanych paczek w widoku ustawień serwera.
Ikona projektu - przyciąga uwagę i jest niejako wizytówką Twojej paczki! Pojawia się w kafelku w liście zainstalowanych paczek w widoku ustawień.

3. Widoczność projektu

Publiczny : Dostępny dla każdego, wyświetla się w liście paczek

w galerii dodatków

Niepubliczny : Nie wyświetla się w liście paczek w galerii dodatków, ale jest możliwy

do udostępnienia przez link.

Prywatny : Dostępny tylko dla Ciebie.

Aby znaleźć projekt niepubliczny, lub prywatny skorzystaj z przycisku "Moje projekty" w galerii dodatków. Przycisk jest dostępny po zalogowaniu na konto.

Kategoria projektu – powinna jak najbliżej precyzować czym jest Twoja paczka. Służy do wyszukiwania paczek w galerii dodatków przez użytkowników.
Gra - Określa do jakiej gry jest przeznaczona Twoja paczka.
Wideo (opcjonalne) - Odtwarza się po najechaniu na kafelek projektu, oraz po kliknięciu w projekt. Powinno być w formacie WebM, być w maksymalnej rozdzielczości 720p, maks. 30fps, oraz rozmiar pliku nie powinien przekraczać 50 MiB.
Miniatura - Wyświetla się na kafelku projektu w galerii dodatków, oraz w widoku wybranego projektu, gdy nie zostało dodane wideo.
Galeria - Wyświetla się na podstronie Twojego projektu. Możesz skorzystać z galerii jeśli chcesz zamieścić w swoim projekcie np. zrzuty ekranu z swojego dodatku.

Szczegółowy opis projektu
- Tłumaczenia
  W Craftserve oferujemy dwa sposoby tłumaczenia opisów paczek na inne języki:
  1. Ręczne tłumaczenie – wybierz preferowany język, klikając odpowiedni przycisk, a następnie edytuj treść w tym języku. Możesz przełączać się między językami i dodawać tłumaczenia ręcznie.
  2. Automatyczne tłumaczenie przez AI – wystarczy, że przygotujesz opis w domyślnym języku projektu. Po 30 minutach od publikacji, tłumaczenia zostaną automatycznie wygenerowane i będą aktualizowane za każdym razem, gdy zaktualizujesz projekt. Aby zmienić język źródłowy dla tłumaczeń, skorzystaj z opcji "Domyślny język projektu", dostępnej pod polami do wprowadzania tłumaczeń.
  Uwaga: Automatyczne tłumaczenia zostaną wygenerowane tylko dla tych języków, dla których pole tłumaczenia jest puste. Jeśli w danym języku został wprowadzony jakikolwiek znak (np. w angielskim, polskim czy niemieckim), tłumaczenie nie zostanie nadpisane.
- Konstruowanie opisu
  W opisie uwzględnij:
  - wymagania Twojej paczki,
  - funkcje i możliwości, jakie oferuje.
  Jeśli tworzysz paczkę modów, dodaj również instrukcję instalacji modyfikacji po stronie użytkownika — tak, aby po instalacji paczki na serwerze użytkownicy mogli łatwo do niego dołączyć.
  Staraj się pisać w sposób przystępny, tak aby także osoby nietechniczne mogły bez problemu przeprowadzić instalację.
Gdy uzupełnisz swój projekt, kliknij przycisk “Opublikuj”, aby zatwierdzić zmiany.

Gotowe! 🚀

Aby zobaczyć swój projekt, przejdź do zakładki „Dodatki”, a następnie wybierz „Moje projekty”.
Pamiętaj, że jeśli Twój projekt nie jest publiczny lub nie ma dodanej wersji do zainstalowania, nie pojawi się w głównym widoku galerii dodatków. W takim przypadku skorzystaj z zakładki „Moje projekty”, gdzie zawsze znajdziesz wszystkie swoje publikacje.

Tworzenie wersji 📦

Masz już swój projekt, ale brakuje w nim wersji, czyli brakuje dodanych plików do projektu, które zostaną pobrane w momencie gdy użytkownik będzie chciał ją zainstalować na swoim serwerze. Aby dodać wersję wejdź w swój projekt, następnie kliknij “Lista wersji”

Kliknij “Lista wersji”
Kliknij "Dodaj wersję"
Uzupełnij typ wersji - te pole oznacza w jakiej fazie rozwoju jest dane wydanie wersji. - Stable oznacza wersję stabilną, która przeszła pełne testy. Jest ona skierowana do użytkowników którzy oczekują w pełni działającego dodatku. - Private oznacza, że wersja jest prywatna, skierowana dla danej grupy odbiorców np. Programistów, lub Twoich testerów. Nie musi być stabilna, może wymagać np. Dodatkowych testów. - Latest to najnowsza wersja, może być stabilna lub nie. Kierowana dla użytkowników, którzy chcą najnowszych funkcji.
Wybierz Sposób instalacji. Rozróżniamy dwa sposoby instalacji:
- Wymaż dane serwera i zainstaluj paczkę - Przed zainstalowaniem Twojego dodatku domyślnie będziemy rekomendować użytkownikowi wymazanie danych swojego serwera, a następnie na czystej instancji zainstalować Twój dodatek.
- Dodaj do istniejącego serwera - Dodamy pliki z Twojej paczki do aktualnego stanu serwera użytkownika.
Wersja pakietu To pole powinno zawierać numer wersji Twojego projektu w formacie SemVer (ang. Semantic Versioning), np. 1.2.3. System instalacji korzysta z tego pola, aby automatycznie rozwiązywać konflikty podczas instalacji projektów.
Format składa się z trzech liczb oddzielonych kropkami:

MAJOR.MINOR.PATCH, czyli:
- 1 – MAJOR: zmienia się, gdy wprowadzasz niekompatybilne zmiany (np. usuwasz lub zmieniasz działanie istniejących funkcji),
- 2 – MINOR: zmienia się, gdy dodajesz nowe, kompatybilne funkcje,
- 3 – PATCH: zmienia się, gdy naprawiasz błędy bez wprowadzania nowych funkcji ani zmian w działaniu.
Przykłady poprawnych wersji:
- 1.0.0 – pierwsze wydanie,
- 1.2.0 – dodano nowe funkcje,
- 1.2.1 – poprawiono drobne błędy,
- 2.0.0 – wprowadzono zmiany łamiące kompatybilność z wcześniejszą wersją.

Uwaga: Użycie poprawnego formatu wersji pomaga użytkownikom rozpoznać, jak istotna była zmiana w paczce i ułatwia zarządzanie aktualizacjami. Aby dowiedzieć się więcej na temat semantycznego wersjonowania skorzystaj z dokumentacji semver

Wersja zawartości - Ta wartość będzie wyświetlać się użytkownikowi jako wersja zainstalowanego dodatku. Możesz wpisać tu taką samą wartość jak w polu Wersja pakietu, lub zastosować swoje niestandardowe wersjonowanie (np. beta, dev-2025-06-11, v2-poprawki, itp.). Pole to nie podlega walidacji – możesz wpisać dowolną wartość, która najlepiej opisuje wersję zawartości projektu z Twojej perspektywy.

Uwaga: Pole to jest opcjonalne i służy jedynie do dodatkowego oznaczania zmian treści – nie wpływa na techniczne działanie paczki.

7. Serwer Wybierz serwer, z którego chcesz udostępnić pliki do swojej paczki. Pliki te zostaną zainstalowane na serwerze użytkownika, który zainstaluje Twoją paczkę. - W zależności od rodzaju paczki: - Jeśli tworzysz paczkę modyfikacji, wybierz pliki, które mają zostać zainstalowane na serwerze użytkownika (np. mody, pluginy). - Jeśli chcesz udostępnić świat z gry, wybierz odpowiedni folder ze światem.

Uwaga: Zwróć szczególną uwagę na strukturę katalogów przy zaznaczaniu plików.
Przykład: jeśli zaznaczysz tylko pliki .jar z folderu plugins, zostaną one zainstalowane w katalogu głównym serwera.
Aby poprawnie zainstalować je w folderze plugins, zaznacz również sam folder plugins wraz z jego zawartością. Twoja ścieżka plików docelowych na serwerze musi pokrywać się z poprawną ścieżką plików.

8. Wybierz paczki

Wybierz inne paczki, które mają zostać automatycznie zainstalowane przed Twoją paczką. System automatycznie wykryje, jakie paczki masz zainstalowane na serwerze, z którego przesyłasz pliki.

Zaznacz wymagane zależności, jeśli Twoja paczka ich potrzebuje. Domyślnie pokażemy zależności używane przez inne Twoje dodatki – możesz je wybrać klikając nazwę paczki, co rozwinie listę opcji.

Przykłady:

Wymagaj paper^1.21 – wymaga, by na serwerze był zainstalowany Paper w wersji >= 1.21.0 i < 2.0.0
Wymagaj game-engine – wymaga jakiegokolwiek silnika gry, niezależnie od wersji czy platformy
Wymagaj minecraft-java-server – wymaga dowolnego silnika serwera Minecraft Java, niezależnie od wersji
Wymagaj paper-api=1.20.1 – wymaga obecności jakiejkolwiek paczki, która udostępnia paper-api w dokładnie wersji 1.20.1
Wymagaj paper=1.21.5 – wymaga, by paczka paper była obecna w dokładnie wersji 1.21.5
Nie wymagaj – Twoja paczka nie ma żadnych zależności i może działać samodzielnie

🔎 Czym się różni `^`, `=`, i `~`?

Przypominjmy sobie na starcie jak działa semantyczne wersjonowanie:

MAJOR.MINOR.PATCH, czyli:

1 – MAJOR: zmienia się, gdy wprowadzasz niekompatybilne zmiany (np. usuwasz lub zmieniasz działanie istniejących funkcji),
2 – MINOR: zmienia się, gdy dodajesz nowe, kompatybilne funkcje,
3 – PATCH: zmienia się, gdy naprawiasz błędy bez wprowadzania nowych funkcji ani zmian w działaniu.

Przykłady poprawnych wersji:
1.0.0 – pierwsze wydanie,
1.2.0 – dodano nowe funkcje,
1.2.1 – poprawiono drobne błędy,
2.0.0 – wprowadzono zmiany łamiące kompatybilność z wcześniejszą wersją.

Znając tę teorię możemy tworzyć następujące wymagania względem wersji paczek:

Operator	Znaczenie	Przykład	Zakres wersji
`^` (caret)	Aktualizacje kompatybilne w obrębie wersji głównej (`major`)	`^1.2.3`	`>=1.2.3 <2.0.0`
`~` (tilde)	Poprawki (`patch`) w obrębie tej samej wersji `minor`	`~1.2.3`	`>=1.2.3 <1.3.0`
`=` (równość)	Dokładna wersja	`=1.2.3`	tylko `1.2.3`
`*` (gwiazdka)	Dowolna wersja	`*`	pasuje do wszystkiego
`-` (hyphen range)	Zakres wersji od–do (włącznie)	`1.2.3 - 1.4.0`	`>=1.2.3 <=1.4.0`

Przykład:

^1.20.0 → pasuje do 1.20.1, 1.21.0, 1.99.99, ale nie do 2.0.0
~1.20.0 → pasuje do 1.20.1, 1.20.9, ale nie do 1.21.0
=1.20.0 → pasuje tylko do 1.20.0

Aby dowiedzieć się więcej na ten temat skorzystaj z dokumentacji 📋

9. Opcje zaawansowane (opcjonalne) - W tym punkcie będziemy tworzyć niestandardowe zależności do Twojego projektu. Po kliknięciu w "Pokaż opcje zaawansowane" pojawi się przycisk "Dodaj zależność". Po kliknięciu masz możliwość dodania własnej zależności. Formularz składa się z 3 pól.

Każde pole jest ze sobą związane. Zależność będzie konstruowana na podstawie NAZWA+TAG
Nazwa - Powinna określać nazwę zależności do której będziesz konfigurował niestandardowe wymagania np. paper-api, lub paper.
tag - Służy do ustalenia niestandardowego selectora. Jeśli wiesz, że Twój dodatek będzie wymagał paper (wartość z pola nazwa) w niestandardowym zakresie np. paper^1.20.1 wtedy użyj ^1.20.1 dla wartości tego pola. Uzupełniając pola nazwa i tag otrzymujemy następujący rezultat: paper^1.20.1
Etykiety (opcjonalne) Każda paczka zawiera swój manifest. Możesz uwzględnić dodatkowo jakie etykiety muszą się w nim znajdować. Przykładowo chce, aby nie dość, że wymagana paczka do działania spełniała zależność paper w wersjach ^1.20.1 to posiadała w polu labels etykiete o kluczu craftserve.com/mod-loader i wartości minecraft-java.

Kliknij tutaj, aby zobaczyć przykładowe etykiety paczek

Klucz	Przykładowa wartość	Opis
`"craftserve.com/game"`	`"minecraft-java"`	Gra, dla której przeznaczony jest dodatek (tu: Minecraft Java)
`"craftserve.com/type"`	`"plugin"`	Typ paczki (np. `plugin`, `mod`, `map`)
`"craftserve.com/package/time"`	`"2025-04-11 15:25:15"`	Data i godzina utworzenia paczki
`"craftserve.com/release/time"`	`"2025-04-11 15:25:15"`	Data i godzina publikacji paczki
`"craftserve.com/require-empty-workspace"`	`"yes"`	Czy paczka wymaga czystej instancji serwera (`yes` / `no`)

Przykładowy manifest paczki

{
    "manifestVersion": "v2",
    "ManifestHash": "sha256-725770a3ffad4d6335fb6828c65b8bd4c558a1c21b817d3155668267f2d04a52",
    "name": "paper",
    "subdir": "/marketplace/paper/sha256-725770a3ffad4d6335fb6828c65b8bd4c558a1c21b817d3155668267f2d04a52",
    "version": "1.21.3-29",
    "versionFormat": "semver",
    "depends": ["java:21"],
    "provides": [
        "game-engine",
        "minecraft-java-server:1.21.3",
        "minecraft-java-server:1.21.x",
        "paper-api:1.21.3",
        "spigot-api:1.21.3",
        "bukkit-api:1.21.3",
        "paper:1.21.3",
        "paper:1.21.x"
    ],
    "set-env": [
        {
            "key": "MINECRAFT_VERSION",
            "value": "1.21.3"
        },
        {
            "key": "21",
            "value": "21"
        }
    ],
    "labels": {
        "craftserve.com/game": "minecraft-java",
        "craftserve.com/java/version": "21",
        "craftserve.com/minecraft-java/version": "1.21.3",
        "craftserve.com/mod-loader": "paper",
        "craftserve.com/package/time": "2024-11-15 15:30:09.385604",
        "craftserve.com/release/time": "2024-11-15 09:09:36.732000",
        "craftserve.com/type": "mod_loader"
    },
    "fileshash": "k1:ff0ad7f85bab891c2d9174d87602f478dd031e206a7cc029ab132ca089da3e0e",
    "downloadfiles": [
        {
            "name": "minecraft_server.jar",
            "url": "https://api.papermc.io/v2/projects/paper/versions/1.21.3/builds/29/downloads/paper-1.21.3-29.jar",
            "hash": "sha256-eb58806b3535646272a2e2ca3b46aae50b7a4ab8f173a493650092f0c1859b89"
        }
    ]
}

Szczegółowy opis : Tutaj możesz opisać dokładnie czego wymaga Twoja wersja, oraz opisać co zmieniło się np. Względem starszej wersji. Pamiętaj, aby dokładnie uzupełniać swoje opisy.
Gdy wszystkie pola zostały uzupełnione, kliknij przycisk “Dodaj wersję”.