-
Notifications
You must be signed in to change notification settings - Fork 1
Erste Schritte
Diese Anleitung führt dich Schritt für Schritt von der Registrierung als Entwickler bis zu deiner ersten laufenden UserApp.
Bevor du loslegen kannst, brauchst du:
- Knuddels Desktop App – Download
- Knuddels-Account mit mindestens Status "Family Mitglied"
- Gültige Handynummer (zur Verifizierung)
- Gültige E-Mail-Adresse
- Akzeptierte Entwickler-AGB
- FTP-Programm – z.B. FileZilla
- Texteditor / IDE – z.B. Visual Studio Code
- Logge dich in die Knuddels Desktop App ein
- Gib in einem beliebigen Channel den Befehl
/apps developerein - Bestätige deine E-Mail-Adresse, Handynummer und die AGB
- Deine FTP-Zugangsdaten werden dir von James (dem Knuddels-Bot) zugeschickt
Tipp: Bewahre deine FTP-Zugangsdaten sicher auf. Bei Problemen mit den Zugangsdaten wende dich an hilfe.knuddels.de.
Tipp: Als Ausgangspunkt stehen offizielle Projekt-Templates bereit – in JavaScript und TypeScript. Sie enthalten eine fertige Projektstruktur mit allen wichtigen Hooks,
app.config, Frontend und README.
Erstelle auf deinem Computer folgende Dateistruktur:
meine-erste-app/
├── main.js # Server-Logik
├── app.config # App-Konfiguration
└── www/
└── index.html # Frontend (HTML-UI)
Die app.config enthält die Metadaten deiner App:
appName = MeineErsteApp
appVersion = 1.0
autoUpdate = true
appDeveloper.knuddelsDEV = DeinNickname
appDeveloper.knuddelsDE = DeinNickname
mayBeInstalledBy.1 = DeinNickname.knuddelsDEV
mayBeInstalledBy.2 = DeinNickname.knuddelsDEHinweis: Ersetze
DeinNicknamedurch deinen tatsächlichen Knuddels-Nicknamen.
var App = {
// Wird aufgerufen, wenn die App gestartet wird
onAppStart: function() {
KnuddelsServer.getDefaultLogger().info('App wurde gestartet!');
},
// Wird aufgerufen, wenn ein Nutzer den Channel betritt
onUserJoined: function(user) {
user.sendPrivateMessage('Willkommen! Gib °>/meineApp|Klick hier<° ein, um die App zu öffnen.');
},
// Events vom Frontend empfangen
onEventReceived: function(user, type, data, appContentSession) {
if (type === "ping") {
if (appContentSession) {
appContentSession.sendEvent('pong', { success: true });
}
}
},
// Chat-Befehle
chatCommands: {
meineApp: function(user, params, command) {
var htmlFile = new HTMLFile("index.html", {});
var popup = AppContent.popupContent(htmlFile, 400, 300);
popup.setResponsive(true);
if (user.canShowAppViewMode(AppViewMode.Popup)) {
user.sendAppContent(popup);
} else {
user.sendPrivateMessage("Die App kann auf deinem Gerät leider nicht angezeigt werden.");
}
}
}
};Wichtig: Alle Hooks und Chat-Befehle werden als Eigenschaften des
App-Objekts definiert. Beachte die Kommas zwischen den Eigenschaften. Mehr dazu unter App-Lifecycle.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<style>
body {
font-family: Arial, sans-serif;
display: flex;
justify-content: center;
align-items: center;
height: 100vh;
margin: 0;
background: #f0f0f0;
}
.container {
text-align: center;
padding: 20px;
}
button {
padding: 10px 20px;
font-size: 16px;
cursor: pointer;
border: none;
background: #4CAF50;
color: white;
border-radius: 5px;
}
</style>
</head>
<body>
<div class="container">
<h1>Meine erste App!</h1>
<p id="status">Verbindung zum Server...</p>
<button onclick="ping()">Ping senden</button>
</div>
<script>
// pageData enthält die Daten, die der Server beim Öffnen mitgeschickt hat
var pageData = {};
if (typeof Client !== 'undefined') {
pageData = Client.pageData;
}
document.getElementById('status').textContent = 'Verbunden!';
function ping() {
if (typeof Client !== 'undefined' && Client.sendEvent) {
Client.sendEvent('ping', {});
}
}
// Events vom Server empfangen
if (typeof Client !== 'undefined') {
Client.addEventListener("pong", function(event) {
document.getElementById('status').textContent = 'Pong erhalten!';
});
}
</script>
</body>
</html>Der onEventReceived-Hook in der main.js reagiert bereits auf den Ping vom Frontend und sendet ein Pong zurück. Du musst nichts weiter hinzufügen.
- Öffne FileZilla und verbinde dich mit den erhaltenen FTP-Zugangsdaten
- Lade den gesamten Projektordner auf den Server hoch
- Gehe in deinen eigenen MyChannel (oder erstelle einen)
- Gib
/appsein - Klicke auf "App installieren"
- Beim ersten Installieren musst du einen AppBot anlegen – gib ihm einen beliebigen Namen
- Fertig! Deine App läuft
Um in deiner IDE (z.B. Visual Studio Code) Autovervollständigung, Typ-Informationen und Inline-Dokumentation für die Knuddels-API zu bekommen, kannst du die offiziellen TypeScript-Typdefinitionen einbinden. Das funktioniert auch, wenn du deinen Server-Code in normalem JavaScript schreibst.
Knuddels stellt die sogenannte User App Library bereit – Typdefinitionen für Server- und Client-API. Es gibt zwei Wege, diese einzubinden.
Initialisiere in deinem App-Ordner ein npm-Projekt und installiere die Typdefinitionen für Server und Client:
cd meine-app
npm init -y
npm install --save-dev @types/knuddels-userapp-backend-api
npm install --save-dev @types/knuddels-webapp-frontend-apiDas erste Paket liefert Typen für den Server-Code (main.js) – also Klassen wie KnuddelsServer, User, AppContent, Channel usw. Das zweite Paket liefert Typen für den Client-Code (www/) – also das Client-Objekt mit sendEvent, addEventListener etc.
Erstelle dann eine Datei jsconfig.json (für JavaScript) oder tsconfig.json (für TypeScript) im App-Ordner:
{
"compilerOptions": {
"target": "ES5",
"checkJs": true,
"noEmit": true,
"typeRoots": ["./node_modules/@types"]
},
"include": ["*.js", "www/**/*.js"],
"exclude": ["node_modules"]
}Tipp: Mit
"checkJs": trueprüft VS Code deinen JavaScript-Code auch auf Typ-Fehler – das hilft, Bugs früh zu erkennen.
Danach erkennt VS Code automatisch Klassen wie KnuddelsServer, User, Client usw. und bietet Autovervollständigung an.
Falls du npm nicht verwenden möchtest, kannst du die Library-Dateien direkt vom Knuddels Developer Portal herunterladen. Dort findest du unter "Unterstützung für Entwicklungsumgebungen" vier Dateien:
-
TypeScript (Server) –
.d.ts-Datei für die Server-API -
JavaScript (Server) –
.js-Datei mit JSDoc-Annotationen für die Server-API -
TypeScript (Client) –
.d.ts-Datei für die Client-API -
JavaScript (Client) –
.js-Datei mit JSDoc-Annotationen für die Client-API
Lade die passenden Dateien herunter und lege sie in deinem Projektordner ab. In den meisten IDEs (VS Code, WebStorm, IntelliJ) reicht es, die Dateien im Projekt zu haben – die IDE erkennt die Typdefinitionen automatisch. Falls nicht, kannst du sie in deiner IDE manuell als Library registrieren (z.B. in WebStorm unter Settings → Languages & Frameworks → JavaScript → Libraries).
Tipp: Die
.js-Varianten mit JSDoc-Annotationen eignen sich, wenn du eine IDE nutzt, die keine TypeScript-Definitionen unterstützt.
Wenn du deinen Server-Code direkt in TypeScript schreiben möchtest, nutze das offizielle TypeScript-Template. Es enthält eine fertige tsconfig.json, ein package.json mit Build-Scripts und die offiziellen Type-Definitionen:
# Template-Ordner kopieren, dann:
cd template-typescript
npm install
npm run buildDer Build-Prozess kompiliert dein TypeScript zu einer main.js im build/-Ordner, die du wie gewohnt per FTP hochladen kannst. Während der Entwicklung kannst du mit npm run watch automatisch bei jeder Änderung neu kompilieren lassen.
Wichtig: Auch bei TypeScript muss das kompilierte JavaScript ES5-kompatibel sein, da der Knuddels-Server die Rhino Engine nutzt. Das Template ist bereits entsprechend konfiguriert (
"target": "ES5"in dertsconfig.json).
-
Autovervollständigung – Tippe
KnuddelsServer.oderClient.und sieh alle verfügbaren Methoden - Parameter-Info – Erfahre direkt in der IDE, welche Parameter eine Methode erwartet
- Fehlerprüfung – Tippfehler in API-Aufrufen werden sofort markiert
- Inline-Dokumentation – Hover über eine Methode, um ihre Beschreibung zu lesen
meine-app/
├── main.js # Server-Logik
├── app.config # App-Konfiguration
├── jsconfig.json # IDE-Konfiguration
├── package.json # npm-Abhängigkeiten
├── node_modules/ # (wird NICHT hochgeladen!)
│ └── @types/
│ ├── knuddels-userapp-backend-api/
│ └── knuddels-webapp-frontend-api/
└── www/
└── index.html
Wichtig: Lade den
node_modules-Ordner,package.jsonundjsconfig.jsonnicht per FTP hoch. Diese Dateien dienen nur der lokalen Entwicklung. Auf dem Knuddels-Server werden nurmain.js,app.configund derwww/-Ordner benötigt.
Der empfohlene Ablauf für die Entwicklung:
- Lokal entwickeln – Ändere deine Dateien in deinem Editor
- Per FTP hochladen – Lade die geänderten Dateien auf den Server
-
App aktualisieren – Gib
/appsein und klicke auf "update/restart" - Testen – Teste die Änderungen im Channel
Wichtig: Nutze den Dev-Server zum Entwickeln und Testen. Auf dem Live-Server (DE) solltest du nur stabile Versionen installieren. Mehr dazu unter Dev-Server.
- Projektstruktur – Verstehe den Aufbau einer UserApp im Detail
- App-Lifecycle – Lerne die verschiedenen Hooks und Events kennen
- Client-Server-Kommunikation – Wie Frontend und Backend miteinander sprechen
- Erste Schritte – Voraussetzungen, Einrichtung, deine erste App
-
Projektstruktur – Dateien, Ordner und
app.config - Dev-Server – Entwicklungsumgebung und Testen
-
App-Lifecycle und Hooks –
onAppStart,onUserJoinedund Co. -
Server-API Grundlagen –
KnuddelsServer,Channel,Logger - Client-Server-Kommunikation – Events zwischen Frontend und Backend
-
Benutzer und Nachrichten –
User,BotUser, Nachrichten senden - HTML-UI und AppContent – Popups, Overlays, Globale Apps-UI
-
Datenspeicherung –
AppPersistence,UserPersistence -
Knuddel und Zahlungen – Transfers, Käufe,
KnuddelAccount - Toplisten – Ranglisten und Highscores
- Globale Apps – Apps im "Apps & Spiele"-Menü
- Quests – Aufgaben für Nutzer
- Externe Server-Kommunikation – HTTP-Requests an externe APIs
- Tutorials – Übersicht aller Tutorials
- Tic-Tac-Toe – Multiplayer-Spiel mit Bestenliste
- Best Practices – Tipps, Limits und häufige Fehler
- FAQ – Häufig gestellte Fragen
- KCode-Formatierung – Nachrichten-Formatierung mit KCode