Z3EDU JSON Specification v1.0
✕
1. Introduction & Overview
TABLE OF CONTENTS: 1. Introduction & Overview 2. Platform Context 3. Complete JSON Structure 4. Field Specifications (Detailed) 5. Advanced Examples 6. AI Course Generation Guide 7. Best Practices & Patterns 8. Integration & Workflow 9. Troubleshooting & Validation 10. Version History & Roadmap WHAT IS Z3EDU? -------------- Z3EDU is a JSON-based course format designed for the Z3 Education Studio WordPress plugin. It enables creation, storage, and sharing of educational courses with rich multimedia content, quizzes, and resource libraries. KEY FEATURES: • Rich text content with WYSIWYG editing (Quill.js) • Embedded images and YouTube videos • Interactive quizzes (3-option multiple choice) • Resource library (text references, PDFs, external links) • Per-lesson customization (width, background color) • Password protection for course security • Course cover images • Import/export functionality
2. Platform Context
FILE FORMAT: • Extension: .z3edu • MIME Type: application/json • Encoding: UTF-8 • Structure: Single JSON object with meta, lessons, resources
3. Complete JSON Structure
ROOT OBJECT
{
"meta": METADATA_OBJECT (required),
"lessons": ARRAY of LESSON_OBJECTS (required, min 1),
"resources": ARRAY of RESOURCE_OBJECTS (optional, default [])
}
4. Field Specifications
(Full metadata, lesson, quiz, resource definitions exactly as provided) All validation rules apply: ✓ Required fields ✓ Optional fields with defaults ✓ Constraints ✓ Unique IDs ✓ Timestamp requirements
5. Advanced Examples
(Complete example and minimal valid example exactly as provided in the spec)
6. AI Course Generation Guide
(Full AI generation guidelines section exactly as provided)
7. Best Practices & Patterns
Use width=80 default Use varied background colors Use structured HTML headers Ensure clean resource references
8. Integration & Workflow
EXPORT: - File saved with .z3edu extension IMPORT: - Must be valid JSON - Must pass validation rules
9. Troubleshooting & Validation
Ensure: • Valid JSON • All required fields present • Quiz structure correct • Resource types valid • IDs unique
10. Version History & Roadmap
v1.0 (Current): - Initial specification - Core lesson/quiz/resource structure - Password protection - Image support - Width/background customization SUPPORT & CONTACT: Developer: Carl M0ICR Project: UKBOTA/WWBOTA Education Platform
Version History
📚 Bookmarks
Z3EDU JSON Specification
Longer Specification
================================================================================
Z3EDU JSON SPECIFICATION v1.0 – COMPREHENSIVE EDITION
Complete Course Format Specification with Context & Examples
================================================================================
TABLE OF CONTENTS:
1. Introduction & Overview
2. Platform Context
3. Complete JSON Structure
4. Field Specifications (Detailed)
5. Advanced Examples
6. AI Course Generation Guide
7. Best Practices & Patterns
8. Integration & Workflow
9. Troubleshooting & Validation
10. Version History & Roadmap
================================================================================
1. INTRODUCTION & OVERVIEW
================================================================================
WHAT IS Z3EDU?
————–
Z3EDU is a JSON-based course format designed for the Z3 Education Studio
WordPress plugin. It enables creation, storage, and sharing of educational
courses with rich multimedia content, quizzes, and resource libraries.
KEY FEATURES:
• Rich text content with WYSIWYG editing (Quill.js)
• Embedded images and YouTube videos
• Interactive quizzes (3-option multiple choice)
• Resource library (text references, PDFs, external links)
• Per-lesson customization (width, background color)
• Password protection for course security
• Course cover images
• Import/export functionality
FILE FORMAT:
• Extension: .z3edu
• MIME Type: application/json
• Encoding: UTF-8
• Structure: Single JSON object with meta, lessons, resources
TYPICAL USE CASES:
1. Educational content creation (schools, training programs)
2. Professional development courses
3. Hobby/interest learning (amateur radio, history, etc.)
4. Documentation and knowledge bases
5. Study guides and exam preparation
================================================================================
2. PLATFORM CONTEXT
================================================================================
THE Z3 EDUCATION STUDIO ECOSYSTEM:
———————————-
Z3 Education Studio is a WordPress plugin that provides:
EDITOR FEATURES:
• Fullscreen WYSIWYG editor (Quill.js powered)
• Resizable/draggable editor window (50%, 75%, 90%, 100%)
• Real-time word and character count
• Drag-to-resize from bottom-right corner
• Double-click header to maximize
• Escape key to close
CONTENT CAPABILITIES:
• Rich text formatting (bold, italic, underline, strikethrough)
• Multiple fonts and sizes
• Text and background colors
• Headers (H1, H2, H3)
• Ordered and unordered lists
• Text alignment (left, center, right, justify)
• Hyperlinks
• Inline images (URL-based)
• Embedded YouTube videos (responsive 16:9)
• Resource links (clickable, opens modal)
COURSE MANAGEMENT:
• Grid view with course cards
• Course images (600x400px recommended)
• Password protection (minimum 6 characters)
• Import/Export courses (.z3edu files)
• Per-lesson width control (50-100% in 10% steps)
• Per-lesson background color
• Live preview of width/color changes
RESOURCE SYSTEM:
• Text references (full-text content)
• PDF documents (external URLs)
• External links (websites, articles)
• Attach resources to multiple lessons
• View resources in modal popups
QUIZ SYSTEM:
• One quiz per lesson (optional)
• Three answer choices
• Instant feedback (correct/incorrect highlighting)
• Visual correct answer indication
TARGET USERS:
• WordPress administrators
• Course creators and educators
• Subject matter experts
• Training departments
• Hobbyist educators
TECHNICAL STACK:
• WordPress plugin architecture
• PHP backend (AJAX handlers)
• JavaScript frontend (ES6+)
• Quill.js WYSIWYG editor
• Custom post type (z3_course)
• LocalStorage for preferences
================================================================================
3. COMPLETE JSON STRUCTURE
================================================================================
FULL ANNOTATED EXAMPLE:
———————–
{
// Course-level metadata
“meta”: {
“title”: “Russian History: The October Revolution”,
“author”: “Dr. Ivan Petrov”,
“version”: “2.1”,
“description”: “A comprehensive 6-lesson course covering the causes, events, and consequences of the 1917 October Revolution in Russia. Includes primary source documents, contemporary photographs, and documentary footage.”,
“duration_hours”: 4.5,
“difficulty”: “intermediate”,
“created”: 1707926400000,
“modified”: 1708531200000,
“password”: “revolution1917”,
“image”: “data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD…”
},
// Array of lessons (1 or more required)
“lessons”: [
{
“id”: “lesson_1707926400001”,
“title”: “Introduction: Russia Before the Revolution”,
“content”: “<h2>The State of Russia in 1917</h2><p>By early 1917, Russia was in crisis. The country had been at war for nearly three years, suffering devastating losses on the Eastern Front. The economy was collapsing, food shortages were widespread, and public confidence in Tsar Nicholas II had evaporated.</p><h3>Key Factors</h3><ul><li><strong>Military defeats:</strong> Over 2 million Russian soldiers had been killed or wounded</li><li><strong>Economic collapse:</strong> Inflation reached 400%, making basic goods unaffordable</li><li><strong>Political crisis:</strong> The Tsar’s autocratic rule was increasingly unpopular</li></ul><p>This lesson examines the conditions that made revolution inevitable.</p>”,
“duration”: 20,
“media”: “”,
“width”: 80,
“backgroundColor”: “#0f172a”,
“resources”: [“res_1707926401111”, “res_1707926401112”],
“quiz”: {
“question”: “What was the approximate death toll of Russian soldiers by early 1917?”,
“options”: [“500,000”, “1 million”, “Over 2 million”],
“correct”: 2
}
},
{
“id”: “lesson_1707926400002”,
“title”: “The February Revolution”,
“content”: “<h2>Spontaneous Uprising</h2><p>The February Revolution began on March 8, 1917 (February 23 in the old Russian calendar) when women textile workers in Petrograd went on strike to protest bread shortages.</p><img src=’https://example.com/feb-revolution-crowd.jpg’ style=’max-width: 100%; border-radius: 8px; margin: 1rem 0;’ alt=’Crowd during February Revolution’><p>Within days, the strike had grown into a mass movement. Soldiers refused to fire on protesters and began joining them instead. By March 15, Tsar Nicholas II had abdicated, ending 300 years of Romanov rule.</p><h3>Key Events Timeline</h3><ol><li>March 8: Women’s Day strikes begin</li><li>March 10: General strike declared in Petrograd</li><li>March 12: Soldiers mutiny and join protesters</li><li>March 15: Tsar Nicholas II abdicates</li></ol><div style=’position: relative; padding-bottom: 56.25%; height: 0; margin: 2rem 0; border-radius: 12px; overflow: hidden; background: #000;’><iframe style=’position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;’ src=’https://www.youtube.com/embed/EXAMPLE_VIDEO_ID’ frameborder=’0′ allowfullscreen></iframe></div>”,
“duration”: 30,
“media”: “”,
“width”: 90,
“backgroundColor”: “#1e293b”,
“resources”: [“res_1707926401113”],
“quiz”: {
“question”: “On which date did Tsar Nicholas II abdicate?”,
“options”: [“March 8, 1917”, “March 12, 1917”, “March 15, 1917”],
“correct”: 2
}
},
{
“id”: “lesson_1707926400003”,
“title”: “The Provisional Government”,
“content”: “<h2>Dual Power: March-October 1917</h2><p>After the Tsar’s abdication, Russia found itself with two competing centers of power: the <strong>Provisional Government</strong> (led by liberal politicians) and the <strong>Petrograd Soviet</strong> (workers’ and soldiers’ councils).</p><p>The Provisional Government, led first by Prince Lvov and then by Alexander Kerensky, faced enormous challenges:</p><ul><li>Continuing the unpopular war</li><li>Managing economic collapse</li><li>Implementing land reform</li><li>Organizing elections</li></ul><p>Meanwhile, Lenin returned from exile in April 1917 and immediately called for <em>’All Power to the Soviets!'</em> in his famous April Theses.</p><p>To understand Lenin’s strategy, read the <a href=’#’ onclick=’Z3Education.viewResource(\”res_1707926401114\”); return false;’ style=’color: var(–z3edu-primary); text-decoration: underline; font-weight: 600;’>📚 April Theses (full text)</a>.</p>”,
“duration”: 25,
“media”: “”,
“width”: 75,
“backgroundColor”: “#0f172a”,
“resources”: [“res_1707926401114”, “res_1707926401115”],
“quiz”: null
}
],
// Resource library (optional)
“resources”: [
{
“id”: “res_1707926401111”,
“type”: “text”,
“title”: “Russian Casualties in World War I”,
“content”: “Official Russian casualty figures from World War I (1914-1917):\n\nKilled in action: 1,700,000\nWounded: 4,950,000\nPrisoners/Missing: 2,500,000\nTotal: 9,150,000\n\nThese staggering losses represented approximately 6% of Russia’s total population and severely undermined both military morale and public support for the war effort.\n\nSource: Ministry of War, Russian Provisional Government, 1917”
},
{
“id”: “res_1707926401112”,
“type”: “pdf”,
“title”: “Photographs of Pre-Revolutionary Russia”,
“url”: “https://archive.org/details/pre-revolution-russia-photos”
},
{
“id”: “res_1707926401113”,
“type”: “link”,
“title”: “February Revolution Timeline (Detailed)”,
“url”: “https://www.historyexample.com/february-revolution-timeline”
},
{
“id”: “res_1707926401114”,
“type”: “text”,
“title”: “Lenin’s April Theses (Summary)”,
“content”: “Vladimir Lenin’s April Theses, presented on April 17, 1917, outlined the Bolshevik strategy:\n\n1. No support for the Provisional Government\n2. End the war immediately\n3. All power to the Soviets\n4. Nationalize all land\n5. Establish workers’ control over production\n6. Form a new International\n7. Change the party name to ‘Communist’\n\nThese radical proposals initially shocked even fellow Bolsheviks, but Lenin’s charisma and tactical brilliance eventually won support. The Theses became the blueprint for the October Revolution.\n\nFull text available in Russian State Archive.”
},
{
“id”: “res_1707926401115”,
“type”: “pdf”,
“title”: “Kerensky’s Memoirs (Excerpt)”,
“url”: “https://example.com/kerensky-memoirs.pdf”
}
]
}
================================================================================
4. FIELD SPECIFICATIONS (DETAILED)
================================================================================
META OBJECT – Complete Reference
———————————
meta.title (STRING, REQUIRED)
Purpose: Primary course identifier displayed in course library
Validation:
– Min length: 1 character
– Max length: 200 characters
– Must be unique (recommended)
Examples:
✓ “Introduction to Amateur Radio”
✓ “World War II: The Pacific Theater”
✓ “Python Programming for Beginners”
✗ “” (empty string – invalid)
✗ “A”.repeat(201) (too long – invalid)
Best Practices:
– Be descriptive and specific
– Include topic and level if relevant
– Avoid special characters that might cause filename issues
– Use title case for professionalism
meta.author (STRING, OPTIONAL, default “”)
Purpose: Credit course creator, enable filtering/searching by author
Validation:
– Max length: 100 characters
Examples:
✓ “Dr. Sarah Johnson”
✓ “Carl M0ICR”
✓ “Physics Department, MIT”
✓ “” (blank is valid)
Best Practices:
– Include credentials if relevant (Dr., PhD, etc.)
– Use callsign for amateur radio content
– Department/organization names acceptable
– Consistent format across courses
meta.version (STRING, OPTIONAL, default “1.0”)
Purpose: Track course revisions, enable version control
Validation:
– Recommended format: MAJOR.MINOR or semver
Examples:
✓ “1.0” (initial release)
✓ “2.3” (major update)
✓ “1.2.1” (minor patch)
Best Practices:
– Increment MAJOR for content overhauls
– Increment MINOR for new lessons/significant updates
– Increment PATCH for typo fixes, small improvements
– Update “modified” timestamp with each version change
meta.description (STRING, OPTIONAL, default “”)
Purpose: Provide course overview for potential students
Validation:
– Max length: 1000 characters (recommended 200-400)
Examples:
✓ “A comprehensive introduction to Python programming covering variables, functions, loops, and object-oriented concepts. Perfect for beginners with no prior coding experience.”
Best Practices:
– First sentence: core topic and level
– Second sentence: what students will learn
– Third sentence: prerequisites or target audience
– Keep concise but informative
– Avoid marketing hype, focus on content
meta.duration_hours (NUMBER, OPTIONAL, default 0)
Purpose: Help students estimate time commitment
Validation:
– Must be non-negative
– Decimals allowed (e.g., 2.5 for 2.5 hours)
Examples:
✓ 3 (3 hours)
✓ 12.5 (12 hours 30 minutes)
✓ 0 (not estimated/not required)
Best Practices:
– Sum of all lesson.duration values / 60
– Add 20-30% buffer for exercises/review
– Round to nearest 0.5 hours
– Update when lessons change
meta.difficulty (STRING, OPTIONAL, default “beginner”)
Purpose: Set student expectations, enable filtering
Validation:
– Must be one of: “beginner”, “intermediate”, “advanced”
Examples:
✓ “beginner” (no prerequisites)
✓ “intermediate” (some experience required)
✓ “advanced” (expert-level content)
Best Practices:
– Beginner: No prior knowledge assumed
– Intermediate: Basic familiarity with topic required
– Advanced: Significant experience needed
– Be honest about difficulty to avoid frustration
meta.created (NUMBER, REQUIRED)
Purpose: Track course age, sort by creation date
Validation:
– Must be Unix timestamp in milliseconds
– JavaScript: Date.now()
– Python: int(time.time() * 1000)
Examples:
✓ 1707926400000 (Feb 14, 2024 18:00:00 GMT)
Best Practices:
– Set once at course creation
– Never modify (even on updates)
– Use UTC timezone
– Milliseconds, not seconds
meta.modified (NUMBER, REQUIRED)
Purpose: Show when course was last updated
Validation:
– Must be Unix timestamp in milliseconds
– Must be >= created timestamp
Examples:
✓ 1708531200000 (Feb 21, 2024 18:00:00 GMT)
Best Practices:
– Update on every save
– JavaScript: Date.now()
– Use for “last updated” displays
– Helps students know if content is current
meta.password (STRING, REQUIRED)
Purpose: Prevent accidental deletion, basic access control
Validation:
– Min length: 6 characters
– No max length (but keep reasonable)
Examples:
✓ “mypass123”
✓ “russian1917”
✓ “SecurePassword!”
✗ “pass” (too short – invalid)
Security Notes:
– Stored in PLAIN TEXT in JSON
– Client-side security ONLY
– Not encrypted or hashed
– Visible to WordPress admins
– Prevents accidental deletion, not malicious access
Best Practices:
– Use memorable password
– Don’t use sensitive passwords
– Share with authorized editors only
– Different password per course (recommended)
meta.image (STRING, OPTIONAL, default “”)
Purpose: Visual course identification in library grid
Validation:
– Must be Data URL (base64 encoded)
– Format: “data:image/[type];base64,[data]”
– Recommended: JPEG or PNG
– Recommended size: 600x400px
– Keep under 500KB for performance
Examples:
✓ “data:image/jpeg;base64,/9j/4AAQSkZJRg…”
✓ “data:image/png;base64,iVBORw0KGgo…”
✓ “” (no image – valid)
Best Practices:
– Aspect ratio: 3:2 (600×400, 900×600, etc.)
– Compress images before encoding
– Use JPEG for photos, PNG for graphics
– Test file size (refresh with image loaded)
– Professional, relevant imagery
LESSONS ARRAY – Complete Reference
———————————–
lessons (ARRAY, REQUIRED)
Purpose: Core course content, sequential learning modules
Validation:
– Must contain at least 1 lesson
– No maximum number of lessons
– All lesson IDs must be unique
Best Practices:
– 3-10 lessons typical for most courses
– Each lesson: single focused topic
– Progressive difficulty (easy to hard)
– Consistent structure across lessons
lessons[].id (STRING, REQUIRED, UNIQUE)
Purpose: Unique identifier for lesson, used for navigation/tracking
Validation:
– Must be unique across all lessons in course
– Recommended format: “lesson_” + timestamp or UUID
Examples:
✓ “lesson_1707926400001”
✓ “lesson_intro”
✓ “lesson_chapter_1”
✗ “lesson_1” (avoid – not globally unique)
Best Practices:
– Use timestamp: “lesson_” + Date.now()
– Or semantic: “lesson_intro”, “lesson_conclusion”
– Consistent format within course
– Never reuse IDs even after deletion
lessons[].title (STRING, REQUIRED)
Purpose: Lesson name displayed in navigation and header
Validation:
– Min length: 1 character
– Max length: 200 characters
Examples:
✓ “Introduction to Quantum Mechanics”
✓ “Chapter 3: The New Deal”
✓ “Exercise: Building Your First Circuit”
Best Practices:
– Clear, descriptive title
– Include lesson number if sequential
– Indicate content type (lecture, exercise, review)
– Parallel structure across lessons
lessons[].content (STRING, REQUIRED)
Purpose: Main lesson content, HTML formatted
Validation:
– Must be valid HTML (Quill-generated or compatible)
– Supported tags: see “HTML Content Formatting” section
Examples: See section 5 for extensive examples
Best Practices:
– Use headings to structure content
– Break into paragraphs (not walls of text)
– Emphasize key concepts with <strong>
– Use lists for enumeration
– Embed media inline where relevant
– Link to resources within content
– Aim for 500-2000 words per lesson
– Proofread for typos and clarity
lessons[].duration (NUMBER, OPTIONAL, default 0)
Purpose: Estimated time to complete lesson (minutes)
Validation:
– Must be non-negative integer
Examples:
✓ 15 (15 minutes)
✓ 30 (30 minutes)
✓ 45 (45 minutes)
✓ 0 (not estimated)
Best Practices:
– Count reading time (250 words/minute)
– Add time for videos
– Add 5-10 min for quizzes
– Round to nearest 5 minutes
– Test with actual students when possible
lessons[].media (STRING, OPTIONAL, default “”)
Purpose: DEPRECATED – legacy field for media URL
Status: Keep for backward compatibility
Recommendation: Use embedded content in “content” field instead
lessons[].width (NUMBER, OPTIONAL, default 80)
Purpose: Content area width as percentage of viewport
Validation:
– Range: 50-100
– Step: 10
– Valid values: 50, 60, 70, 80, 90, 100
Examples:
✓ 80 (default – balanced)
✓ 100 (full width for images)
✓ 60 (narrow for text-heavy)
Best Practices:
– 80: Default for most lessons
– 100: Image galleries, wide tables
– 60-70: Text-heavy philosophical content
– 90: Mixed content with some images
lessons[].backgroundColor (STRING, OPTIONAL, default “#0f172a”)
Purpose: Lesson content area background color
Validation:
– Must be valid hex color code
– Format: “#RRGGBB” (6 digits)
Examples:
✓ “#0f172a” (dark blue – default)
✓ “#1e293b” (slate)
✓ “#ffffff” (white)
✗ “blue” (invalid – must be hex)
✗ “#fff” (invalid – must be 6 digits)
Best Practices:
– Default works for most content
– Vary for visual interest
– Ensure text contrast (WCAG AA minimum)
– Test readability before finalizing
– Keep consistent within topic sections
lessons[].resources (ARRAY of STRING, OPTIONAL, default [])
Purpose: Link supplementary materials to lesson
Validation:
– Array of resource IDs (strings)
– Each ID must exist in root “resources” array
Examples:
✓ [“res_1707926401111”]
✓ [“res_1707926401111”, “res_1707926401112”]
✓ [] (no resources – valid)
Best Practices:
– Only include directly relevant resources
– Order by importance
– 1-3 resources typical per lesson
– Use descriptive resource titles
– Reference in lesson content when appropriate
lessons[].quiz (QUIZ_OBJECT or null, OPTIONAL, default null)
Purpose: Assess comprehension, reinforce learning
Validation:
– Must be valid QUIZ_OBJECT or null
– Only one quiz per lesson
Examples: See QUIZ_OBJECT specification
Best Practices:
– Include quiz for knowledge-based lessons
– Skip for exercises/practice lessons
– Place at end of lesson conceptually
– Write clear, unambiguous questions
– Ensure one definitively correct answer
QUIZ OBJECT – Complete Reference
———————————
quiz.question (STRING, REQUIRED)
Purpose: Assessment question text
Validation:
– Max length: 500 characters (recommended 50-150)
Examples:
✓ “What year did World War II end?”
✓ “Which of the following is NOT a primary color?”
✓ “According to Einstein’s theory, what is the relationship between energy and mass?”
Best Practices:
– Be specific and unambiguous
– Avoid trick questions
– Test single concept per question
– Use proper grammar and punctuation
– Avoid “all of the above” / “none of the above”
quiz.options (ARRAY of STRING, REQUIRED)
Purpose: Multiple choice answer options
Validation:
– EXACTLY 3 strings required
– Each string max 200 characters
Examples:
✓ [“1943”, “1944”, “1945”]
✓ [“Red, Yellow, Blue”, “Red, Green, Blue”, “Cyan, Magenta, Yellow”]
Best Practices:
– Similar length for all options
– Plausible distractors (not obviously wrong)
– Alphabetical or logical order
– Consistent format (all dates, all names, etc.)
– Avoid “none of the above” as option
quiz.correct (NUMBER, REQUIRED)
Purpose: Index of correct answer
Validation:
– Range: 0-2 (zero-indexed)
– 0 = first option, 1 = second, 2 = third
Examples:
✓ 0 (first option correct)
✓ 1 (second option correct)
✓ 2 (third option correct)
✗ 3 (invalid – out of range)
Best Practices:
– Randomize correct position across quizzes
– Don’t always make last option correct
– Double-check index matches intention
RESOURCES ARRAY – Complete Reference
————————————-
resources (ARRAY of RESOURCE_OBJECT, OPTIONAL, default [])
Purpose: Supplementary materials referenced in lessons
Validation:
– All resource IDs must be unique
– Referenced resources must exist in lessons[].resources
Best Practices:
– Create library of reusable resources
– Same resource can be referenced by multiple lessons
– Organize by type (all text, all PDFs, etc.)
– Use meaningful IDs
resources[].id (STRING, REQUIRED, UNIQUE)
Purpose: Unique identifier for resource
Validation:
– Must be unique across all resources
– Recommended format: “res_” + timestamp
Examples:
✓ “res_1707926401111”
✓ “res_treaty_brest_litovsk”
Best Practices:
– Use timestamp for uniqueness
– Or semantic names for clarity
– Consistent format within course
resources[].type (STRING, REQUIRED)
Purpose: Determine how resource is displayed/accessed
Validation:
– Must be one of: “text”, “pdf”, “link”
Meanings:
– “text”: Full text content shown in modal
– “pdf”: External PDF opened in new tab
– “link”: External webpage opened in new tab
Examples:
✓ “text” (for definitions, excerpts, primary sources)
✓ “pdf” (for downloadable documents)
✓ “link” (for external websites)
resources[].title (STRING, REQUIRED)
Purpose: Resource name displayed to students
Validation:
– Max length: 200 characters
Examples:
✓ “Treaty of Brest-Litovsk (Full Text)”
✓ “Lenin’s April Theses”
✓ “Soviet Archive: Revolutionary Documents”
Best Practices:
– Descriptive and specific
– Include document type if relevant
– Use consistent naming convention
resources[].content (STRING, REQUIRED for type=”text”)
Purpose: Full text of resource
Validation:
– Required if type=”text”
– Ignored if type=”pdf” or “link”
Examples: See section 5
Best Practices:
– Include source attribution
– Format with line breaks for readability
– Keep under 5000 characters for performance
– Copyright-friendly content only
resources[].url (STRING, REQUIRED for type=”pdf” or “link”)
Purpose: External resource location
Validation:
– Required if type=”pdf” or type=”link”
– Must be valid URL (http:// or https://)
– Ignored if type=”text”
Examples:
✓ “https://archive.org/details/russian-revolution”
✓ “https://example.com/documents/treaty.pdf”
Best Practices:
– Use stable URLs (not shortlinks)
– Prefer archive.org for historical documents
– Test links before publishing
– Consider link rot (check periodically)
================================================================================
5. ADVANCED EXAMPLES
================================================================================
EXAMPLE 1: Text-Heavy Lesson with Formatting
———————————————
{
“id”: “lesson_philosophy_101”,
“title”: “Introduction to Existentialism”,
“content”: “<h2>What is Existentialism?</h2><p>Existentialism is a philosophical movement that emphasizes <strong>individual existence, freedom, and choice</strong>. It emerged in the 19th and 20th centuries as a reaction against traditional philosophical systems.</p><h3>Core Tenets</h3><ol><li><strong>Existence precedes essence:</strong> Humans exist first, then define themselves through their choices</li><li><strong>Radical freedom:</strong> We are fundamentally free to choose our actions</li><li><strong>Authenticity:</strong> Living according to one’s own values rather than conforming to society</li><li><strong>Angst:</strong> The anxiety that comes from recognizing our freedom and responsibility</li></ol><p>Jean-Paul Sartre famously wrote: <em>\”Man is condemned to be free; because once thrown into the world, he is responsible for everything he does.\”</em></p><p>This philosophy has profound implications for how we understand <span style=’color: rgb(230, 0, 0);’>personal responsibility</span>, <span style=’color: rgb(0, 153, 0);’>moral decision-making</span>, and <span style=’color: rgb(0, 102, 204);’>the meaning of life</span>.</p>”,
“duration”: 25,
“width”: 70,
“backgroundColor”: “#1e293b”,
“resources”: [“res_sartre_quote”, “res_existentialism_reading_list”],
“quiz”: {
“question”: “According to existentialism, what comes first?”,
“options”: [“Essence”, “Existence”, “Society”],
“correct”: 1
}
}
EXAMPLE 2: Image-Heavy Lesson
——————————
{
“id”: “lesson_architecture_gothic”,
“title”: “Gothic Architecture: Key Features”,
“content”: “<h2>Identifying Gothic Architecture</h2><p>Gothic architecture, which flourished in Europe from the 12th to 16th centuries, is characterized by distinctive structural and decorative elements.</p><h3>The Pointed Arch</h3><img src=’https://example.com/pointed-arch.jpg’ style=’max-width: 100%; border-radius: 8px; margin: 1rem 0;’ alt=’Gothic pointed arch’><p>Unlike the rounded Romanesque arch, the Gothic <strong>pointed arch</strong> distributes weight more efficiently, allowing for taller structures.</p><h3>Flying Buttresses</h3><img src=’https://example.com/flying-buttress.jpg’ style=’max-width: 100%; border-radius: 8px; margin: 1rem 0;’ alt=’Flying buttress supporting cathedral wall’><p>These external support structures transfer the weight of the roof and walls, enabling larger windows and thinner walls.</p><h3>Rose Windows</h3><img src=’https://example.com/rose-window.jpg’ style=’max-width: 100%; border-radius: 8px; margin: 1rem 0;’ alt=’Notre-Dame rose window’><p>Massive circular stained glass windows became possible thanks to the improved structural support of Gothic design.</p>”,
“duration”: 20,
“width”: 100,
“backgroundColor”: “#0f172a”,
“resources”: [“res_gothic_cathedrals_list”],
“quiz”: null
}
EXAMPLE 3: Video-Based Lesson
——————————
{
“id”: “lesson_chemistry_reactions”,
“title”: “Lab Demo: Exothermic Reactions”,
“content”: “<h2>Observing Energy Release</h2><p>In this lesson, we’ll observe several exothermic reactions – chemical reactions that release energy in the form of heat and light.</p><h3>Safety First</h3><p><strong style=’color: rgb(230, 0, 0);’>Warning:</strong> These demonstrations should only be performed by qualified instructors in proper laboratory settings. Do not attempt at home.</p><h3>Demonstration 1: Thermite Reaction</h3><div style=’position: relative; padding-bottom: 56.25%; height: 0; margin: 2rem 0; border-radius: 12px; overflow: hidden; background: #000;’><iframe style=’position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;’ src=’https://www.youtube.com/embed/THERMITE_VIDEO_ID’ frameborder=’0′ allowfullscreen></iframe></div><p>The thermite reaction between aluminum and iron oxide produces temperatures exceeding 2,500°C (4,500°F). The reaction is: <strong>2Al + Fe₂O₃ → 2Fe + Al₂O₃ + heat</strong></p><h3>Demonstration 2: Elephant’s Toothpaste</h3><div style=’position: relative; padding-bottom: 56.25%; height: 0; margin: 2rem 0; border-radius: 12px; overflow: hidden; background: #000;’><iframe style=’position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;’ src=’https://www.youtube.com/embed/TOOTHPASTE_VIDEO_ID’ frameborder=’0′ allowfullscreen></iframe></div><p>The rapid decomposition of hydrogen peroxide catalyzed by potassium iodide creates a spectacular foam eruption.</p>”,
“duration”: 35,
“width”: 90,
“backgroundColor”: “#0f172a”,
“resources”: [“res_safety_guidelines”, “res_reaction_equations”],
“quiz”: {
“question”: “What type of reaction releases energy?”,
“options”: [“Endothermic”, “Exothermic”, “Isothermic”],
“correct”: 1
}
}
EXAMPLE 4: Resource-Rich Lesson
——————————–
{
“id”: “lesson_primary_sources”,
“title”: “Analyzing the Declaration of Independence”,
“content”: “<h2>Reading Primary Sources</h2><p>The Declaration of Independence is one of the most important documents in American history. Written primarily by Thomas Jefferson in June-July 1776, it announced the thirteen colonies’ separation from British rule.</p><h3>Key Passages</h3><p>The Declaration opens with one of the most famous sentences in political philosophy:</p><p><em>\”We hold these truths to be self-evident, that all men are created equal, that they are endowed by their Creator with certain unalienable Rights, that among these are Life, Liberty and the pursuit of Happiness.\”</em></p><p>To read the complete text, see <a href=’#’ onclick=’Z3Education.viewResource(\”res_declaration_full_text\”); return false;’ style=’color: var(–z3edu-primary); text-decoration: underline; font-weight: 600;’>📚 Declaration of Independence (Full Text)</a>.</p><h3>Historical Context</h3><p>For background on the events leading to independence, review <a href=’#’ onclick=’Z3Education.viewResource(\”res_road_to_independence\”); return false;’ style=’color: var(–z3edu-primary); text-decoration: underline; font-weight: 600;’>📚 The Road to Independence: 1763-1776</a>.</p><h3>Analysis Tools</h3><p>Use this <a href=’#’ onclick=’Z3Education.viewResource(\”res_rhetorical_analysis\”); return false;’ style=’color: var(–z3edu-primary); text-decoration: underline; font-weight: 600;’>📄 Rhetorical Analysis Framework</a> to examine Jefferson’s persuasive techniques.</p>”,
“duration”: 30,
“width”: 80,
“backgroundColor”: “#1e293b”,
“resources”: [“res_declaration_full_text”, “res_road_to_independence”, “res_rhetorical_analysis”],
“quiz”: {
“question”: “Who was the primary author of the Declaration of Independence?”,
“options”: [“Benjamin Franklin”, “Thomas Jefferson”, “John Adams”],
“correct”: 1
}
}
EXAMPLE 5: Minimal Lesson (Valid)
———————————-
{
“id”: “lesson_break”,
“title”: “Mid-Course Break”,
“content”: “<p>You’ve completed half the course! Take a 10-minute break before continuing.</p>”
}
Note: This is technically valid but not recommended. Include more content for better learning experiences.
================================================================================
6. AI COURSE GENERATION GUIDE
================================================================================
PROMPTING AI TO GENERATE COURSES:
———————————-
When using AI (ChatGPT, Claude, etc.) to generate Z3EDU courses:
BASIC PROMPT TEMPLATE:
“Generate a Z3EDU format course about [TOPIC] following the Z3EDU JSON Specification v1.0. The course should:
– Have 5-7 lessons
– Include rich HTML content with headers, lists, and emphasis
– Add 1-2 quizzes
– Create 3-5 resources
– Use appropriate difficulty level: [beginner/intermediate/advanced]
– Target duration: [X] hours”
ADVANCED PROMPT TEMPLATE:
“Create a comprehensive Z3EDU course on [TOPIC] with the following requirements:
COURSE METADATA:
– Title: [Specific title]
– Author: [Your name]
– Difficulty: [Level]
– Duration: [X hours]
– Description: [1-2 sentence overview]
LESSON STRUCTURE:
– 6 lessons total
– Lesson 1: Introduction and overview
– Lessons 2-5: Core content (progressive difficulty)
– Lesson 6: Summary and next steps
– Each lesson: 500-1000 words
– Include 2-3 headings per lesson
– Use lists for key points
– Add emphasis to important concepts
MULTIMEDIA:
– Suggest 3-4 relevant YouTube videos (provide example VIDEO_IDs)
– Include 2-3 images per visual lesson (provide example URLs)
QUIZZES:
– Include quiz for lessons 2, 4, and 6
– Questions should test comprehension
– Avoid trick questions
RESOURCES:
– Create 5 text resources (definitions, excerpts, summaries)
– Add 2 PDF links (to real documents if possible)
– Include 1-2 external links to authoritative sources
FORMATTING:
– Use proper HTML formatting (Quill-compatible)
– Vary lesson widths (70-90%)
– Use 2-3 different background colors for visual variety
Follow the Z3EDU JSON Specification v1.0 exactly. Output valid JSON ready to save as .z3edu file.”
EXAMPLE SPECIFIC PROMPTS:
————————-
For History Course:
“Generate a Z3EDU course on ‘The French Revolution’ (intermediate level, 4 hours). Include 6 lessons covering causes, events, key figures, and consequences. Add primary source excerpts as text resources. Include timeline graphics and documentary video suggestions.”
For Programming Course:
“Create a Z3EDU beginner Python course (8 hours, 7 lessons). Cover variables, functions, loops, lists, dictionaries, file I/O, and a final project. No videos needed. Include code examples in <pre> tags. Add practice exercises as resources.”
For Science Course:
“Generate a Z3EDU course on ‘Climate Change Science’ (intermediate, 5 hours, 6 lessons). Include data visualizations, research paper links, and video explainers. Add quizzes testing scientific literacy.”
AI OUTPUT VALIDATION CHECKLIST:
——————————–
After AI generates course JSON, verify:
□ Valid JSON syntax (paste into JSON validator)
□ All required fields present
□ Unique IDs for lessons and resources
□ Password is 6+ characters
□ HTML content is well-formed
□ Resource IDs in lessons match resource array
□ Quiz correct index is 0-2
□ Timestamps are reasonable
□ No placeholder text left (TODO, EXAMPLE, etc.)
COMMON AI GENERATION ISSUES:
—————————–
Issue: AI uses invalid HTML tags
Fix: Specify “Quill-compatible HTML only” in prompt
Issue: AI generates >3 quiz options
Fix: Emphasize “EXACTLY 3 options” in prompt
Issue: AI forgets to include password
Fix: Add “password is REQUIRED, minimum 6 characters” to prompt
Issue: Resource IDs don’t match references
Fix: Ask AI to “verify all resource ID references”
Issue: Timestamps are unrealistic (far future/past)
Fix: Provide current timestamp in prompt: “Use created: 1707926400000 and modified: 1707926400000”
ITERATIVE IMPROVEMENT:
———————-
1. Generate initial course
2. Import into Z3 Education Studio
3. Review in editor
4. Export with improvements
5. Use as example for next generation
6. Build prompt library of successful patterns
================================================================================
7. BEST PRACTICES & PATTERNS
================================================================================
CONTENT WRITING BEST PRACTICES:
——————————–
Structure:
– Start each lesson with clear learning objective
– Use H2 for main sections, H3 for subsections
– Break content into 3-5 major sections per lesson
– End with summary or key takeaways
Formatting:
– Paragraphs: 2-4 sentences max
– Lists: Use for 3+ related items
– Emphasis: <strong> for key terms (first mention)
– Colors: Sparingly, for critical warnings or highlights
Engagement:
– Ask rhetorical questions
– Use concrete examples
– Include relevant anecdotes
– Connect to real-world applications
Accessibility:
– Descriptive link text (not “click here”)
– Alt text for images
– Color is not sole means of conveying information
– Proper heading hierarchy (don’t skip levels)
QUIZ DESIGN PATTERNS:
———————
Good Quiz Question Examples:
Knowledge recall:
“What year did the Treaty of Versailles end World War I?”
Options: [“1918”, “1919”, “1920”]
Comprehension:
“According to the lesson, what was the PRIMARY cause of the Great Depression?”
Options: [“Stock market crash”, “Bank failures”, “Dust Bowl”]
Application:
“If you need to store a list of student names in Python, which data structure is most appropriate?”
Options: [“Dictionary”, “List”, “Tuple”]
AVOID:
– Trick questions with subtle wording
– “All of the above” / “None of the above”
– True/false reformatted as multiple choice
– Questions with two plausible correct answers
– Unnecessarily complex language
RESOURCE LIBRARY PATTERNS:
————————–
Effective Resource Types:
Text Resources:
– Glossary of terms
– Historical document excerpts
– Case study details
– Formula reference sheets
– Timeline summaries
PDF Resources:
– Research papers
– Government reports
– Technical specifications
– Historical photographs collections
– Practice worksheets
Link Resources:
– Interactive simulations
– Official organization websites
– Museum virtual tours
– Academic databases
– Video playlists
Organization Tips:
– Group related resources
– Use consistent naming: “[Type]: [Title]”
– Order by relevance (most important first)
– Limit to 3-5 resources per lesson
– Reuse resources across lessons when appropriate
LESSON PROGRESSION PATTERNS:
—————————-
Typical Course Arc:
Lesson 1: Introduction
– Course overview
– Learning objectives
– Prerequisites review
– Motivation (why this matters)
Lessons 2-N: Core Content
– Progressive difficulty
– Build on previous lessons
– Mix theory and examples
– Include practice opportunities
Final Lesson: Conclusion
– Recap main concepts
– Synthesize learnings
– Next steps/further study
– Course completion acknowledgment
Within-Lesson Pattern:
1. Hook (1 paragraph)
2. Context/Background (1-2 paragraphs)
3. Main Content (3-5 sections)
4. Examples/Applications
5. Summary/Key Points
6. Quiz (optional)
VISUAL DESIGN PATTERNS:
———————–
Layout Choices:
width: 60-70%
– Dense text (philosophy, literature analysis)
– Maximize readability
– Minimize line length
width: 80% (default)
– Balanced content (most lessons)
– Good for mixed text/media
– Professional appearance
width: 90-100%
– Image galleries
– Wide tables or diagrams
– Video-centric lessons
– Code examples with long lines
Background Color Strategies:
Single Color Throughout:
– Consistent, professional
– Best for formal courses
– Use default #0f172a
Varied by Topic:
– Different color per major section
– Visual organization cue
– Keep contrast high
Accent for Special Lessons:
– Different color for intro/conclusion
– Highlight practice lessons
– Mark assessment sections
METADATA STRATEGIES:
——————–
Versioning Approach:
1.0 – Initial release
1.1 – Minor content updates (typos, small additions)
1.2 – Added quiz or resource
2.0 – Major content overhaul or restructure
2.1 – New lesson added
3.0 – Complete course redesign
Duration Estimation:
Reading: 250 words per minute
+ Videos: actual runtime
+ Quizzes: 5-10 minutes each
+ Exercises: 2x reading time
= Total × 1.3 (buffer for comprehension)
Difficulty Calibration:
Beginner:
– No prerequisites assumed
– Define all terms
– Step-by-step explanations
– Lots of examples
Intermediate:
– Basic knowledge assumed
– Some terms used without definition
– More complex examples
– Synthesize concepts
Advanced:
– Significant background required
– Technical vocabulary expected
– Complex case studies
– Critical analysis required
================================================================================
8. INTEGRATION & WORKFLOW
================================================================================
TYPICAL CREATION WORKFLOWS:
—————————
Workflow 1: Manual Creation in Editor
1. Create course in Z3 Education Studio
2. Set metadata (title, password, image)
3. Write lesson content in fullscreen editor
4. Add quizzes
5. Create resources
6. Link resources to lessons
7. Export .z3edu file for backup
Workflow 2: AI-Generated with Manual Refinement
1. Generate course JSON with AI (ChatGPT/Claude)
2. Validate JSON syntax
3. Import into Z3 Education Studio
4. Review and edit content
5. Add/improve multimedia
6. Test quizzes
7. Export final version
Workflow 3: Template-Based Batch Creation
1. Create course template .z3edu
2. Duplicate and modify for each topic
3. Use find-replace for bulk updates
4. Import batch into WordPress
5. Fine-tune individually
6. Export final versions
Workflow 4: Collaborative Development
1. Team member A creates outline (meta, lesson titles)
2. Export and share .z3edu
3. Team member B writes lesson 1-3 content
4. Team member C writes lesson 4-6 content
5. Team member D creates all resources
6. Import individual pieces
7. Team lead reviews and merges
8. Export final consolidated course
IMPORT/EXPORT BEST PRACTICES:
——————————
Before Export:
□ Spell-check all content
□ Test all resource links
□ Verify quiz answers are correct
□ Check image loads properly
□ Confirm password is memorable
Export Strategy:
– Filename: descriptive-title-vX.X.z3edu
– Backup before major changes
– Version control recommended (Git)
– Include version number in filename
Before Import:
□ Validate JSON syntax
□ Check file size (<5MB recommended)
□ Verify password is known
□ Back up existing courses
Import Troubleshooting:
– “Invalid file”: Check JSON syntax
– “No password”: Add meta.password field
– Missing content: Check required fields
– Import succeeds but looks wrong: Check HTML formatting
BACKUP STRATEGIES:
——————
Recommended:
1. Export after every major edit session
2. Store .z3edu files in cloud storage (Google Drive, Dropbox)
3. Use Git for version control
4. Keep 3-5 recent versions
5. Archive old versions annually
Naming Convention:
course-title-YYYYMMDD-vX.X.z3edu
Example:
russian-revolution-20240214-v2.1.z3edu
Version Control with Git:
“`bash
git init z3edu-courses
cd z3edu-courses
git add russian-revolution.z3edu
git commit -m “Initial version of Russian Revolution course”
git tag v1.0
[make updates]
git add russian-revolution.z3edu
git commit -m “Added Lenin biography resource”
git tag v1.1
“`
MULTI-PLATFORM WORKFLOW:
————————-
Scenario: Create on Mac, edit on Windows, publish on Linux server
1. Create course on Mac (Z3 Education Studio in local WordPress)
2. Export .z3edu file
3. Store in cross-platform location (Dropbox, Google Drive)
4. Import on Windows WordPress instance
5. Make edits
6. Export updated version
7. Upload to production Linux server
8. Import final version
Key Considerations:
– Line endings (CRLF vs LF): JSON doesn’t care
– File paths in HTML: Use URLs, not local paths
– Images: Use data URLs (base64) or remote URLs
– Fonts: Stick to web-safe fonts
INTEGRATION WITH OTHER TOOLS:
——————————
Convert from Markdown to Z3EDU:
1. Write lessons in Markdown
2. Use Pandoc to convert to HTML: `pandoc lesson.md -o lesson.html`
3. Copy HTML into lesson content
4. Wrap in proper Z3EDU JSON structure
5. Import
Convert from PowerPoint to Z3EDU:
1. Export PowerPoint as images
2. Upload images to hosting
3. Create lesson with embedded images
4. Add speaker notes as content
5. Build Z3EDU JSON manually
Integrate with LMS:
– Z3EDU for content authoring
– Export final version
– Convert content to SCORM package (custom script)
– Upload to Moodle/Canvas/Blackboard
AUTOMATION OPPORTUNITIES:
————————–
Scripted Course Generation:
“`python
import json
from datetime import datetime
def generate_course(title, lessons_data):
course = {
“meta”: {
“title”: title,
“author”: “Automated Generator”,
“version”: “1.0”,
“created”: int(datetime.now().timestamp() * 1000),
“modified”: int(datetime.now().timestamp() * 1000),
“password”: “default123”
},
“lessons”: [],
“resources”: []
}
for i, lesson_data in enumerate(lessons_data):
lesson = {
“id”: f”lesson_{int(datetime.now().timestamp() * 1000) + i}”,
“title”: lesson_data[“title”],
“content”: f”<p>{lesson_data[‘content’]}</p>”,
“duration”: lesson_data.get(“duration”, 15),
“width”: 80,
“backgroundColor”: “#0f172a”,
“resources”: [],
“quiz”: None
}
course[“lessons”].append(lesson)
return course
# Usage
lessons = [
{“title”: “Introduction”, “content”: “Welcome to this course…”},
{“title”: “Chapter 1”, “content”: “In this chapter…”},
]
course_json = generate_course(“My Automated Course”, lessons)
with open(“course.z3edu”, “w”) as f:
json.dump(course_json, f, indent=2)
“`
Bulk Resource Creation:
– Scrape Wikipedia for topic summaries
– Create text resource for each
– Add to course resources array
– Link to relevant lessons
Content Analysis:
– Parse exported .z3edu
– Count words per lesson
– Analyze reading level (Flesch-Kincaid)
– Generate course statistics
– Identify lessons needing expansion
================================================================================
9. TROUBLESHOOTING & VALIDATION
================================================================================
COMMON ERRORS AND SOLUTIONS:
—————————–
Error: “Course has no password”
Cause: meta.password missing or empty
Solution: Add “password”: “yourpass123” to meta object
Error: “Invalid JSON”
Cause: Syntax error (missing comma, bracket, etc.)
Solution: Use JSON validator (jsonlint.com)
Common culprits:
– Trailing comma after last object property
– Missing closing bracket/brace
– Unescaped quotes in content
Error: “Lesson not loading”
Cause: Malformed HTML in content
Solution: Check content for unclosed tags
Use HTML validator
Ensure quotes are properly escaped
Error: “Quiz not working”
Cause: Incorrect quiz structure
Solution: Verify:
– Exactly 3 options
– correct index is 0, 1, or 2
– All fields present (question, options, correct)
Error: “Resource not found”
Cause: Resource ID in lesson doesn’t match resource array
Solution: Copy exact ID from resource object
Check for typos
Ensure resource exists in resources array
Error: “Image not displaying”
Cause: Invalid base64 data or URL
Solution:
– Check data URL format: data:image/jpeg;base64,…
– Verify base64 encoding is valid
– Test URL in browser first
– Check file size (keep under 500KB)
VALIDATION CHECKLIST:
———————
Before importing .z3edu file:
JSON Structure:
□ Valid JSON syntax (no parse errors)
□ Root object has meta, lessons, resources
□ All required fields present
□ All IDs are unique
Metadata:
□ Title is not empty
□ Password is 6+ characters
□ Timestamps are valid numbers
□ Difficulty is beginner/intermediate/advanced
□ Image is valid data URL or empty string
Lessons:
□ At least one lesson exists
□ Each lesson has unique ID
□ Each lesson has title and content
□ Content is valid HTML
□ Width is 50, 60, 70, 80, 90, or 100
□ Background color is valid hex code
□ Referenced resource IDs exist
Quizzes:
□ Question is present if quiz exists
□ Exactly 3 options
□ Correct index is 0, 1, or 2
□ All fields are strings/numbers as specified
Resources:
□ Each resource has unique ID
□ Type is text, pdf, or link
□ Title is present
□ Content exists if type is text
□ URL exists if type is pdf or link
□ URLs are valid (http:// or https://)
TESTING WORKFLOW:
—————–
After creating course:
1. Import into Z3 Education Studio
2. Open course
3. Navigate through all lessons
4. Check all media loads
5. Click all resource links
6. Take all quizzes
7. Verify correct answers highlighted
8. Test width/background in study mode
9. Export and re-import (round-trip test)
10. Compare exported JSON to original
Quality Assurance Checklist:
□ No spelling/grammar errors
□ All images load correctly
□ All videos play
□ All external links work
□ Quizzes have correct answers
□ Content flows logically
□ Difficulty is appropriate for level
□ Duration estimates are realistic
□ Resources are relevant
□ Visual design is consistent
PERFORMANCE CONSIDERATIONS:
—————————
File Size:
– Target: <2MB per course
– Warning: >5MB may cause slow loads
– Critical: >10MB will likely fail
Recommendations:
– Compress images before encoding to base64
– Use external URLs for large images when possible
– Limit embedded videos (use links instead for large courses)
– Keep resource content under 5000 characters each
Load Time:
– Import time proportional to file size
– Large courses (20+ lessons): expect 5-10 second import
– Optimize by splitting into multiple courses if needed
Browser Performance:
– Very long lessons (>5000 words) may lag in editor
– Break into multiple lessons if editor becomes slow
– Test in target browsers (Chrome, Firefox, Safari, Edge)
DEBUGGING TECHNIQUES:
———————
JSON Validation:
1. Copy entire course JSON
2. Paste into jsonlint.com
3. Click “Validate JSON”
4. Fix any syntax errors reported
5. Re-test import
Content Validation:
1. Copy lesson.content value
2. Create test.html file
3. Paste content into <body>
4. Open in browser
5. Verify rendering is correct
Resource Link Testing:
1. Extract all resource URLs
2. Open each in new browser tab
3. Verify they load correctly
4. Replace broken links
5. Re-import course
Quiz Testing:
1. Take quiz as a student
2. Note correct answer shown
3. Verify it matches quiz.correct index
4. Try wrong answers
5. Confirm they’re marked incorrect
COMMON PITFALLS:
—————-
1. Forgetting to update modified timestamp
→ Always set to Date.now() on save
2. Using same ID for multiple lessons/resources
→ Always generate unique IDs
3. Copying HTML from Word/Google Docs
→ Clean up formatting, remove inline styles
4. Not testing quizzes
→ Always verify correct answer is actually correct
5. Assuming links will always work
→ Use archive.org for important historical documents
6. Forgetting to escape quotes in JSON strings
→ Use \” for quotes inside string values
7. Not providing password on import
→ Always include password in meta object
8. Using http:// instead of https://
→ Prefer https:// for all external resources
================================================================================
10. VERSION HISTORY & ROADMAP
================================================================================
VERSION HISTORY:
—————-
v1.0 (February 2024) – Current
– Initial Z3EDU specification release
– Core lesson/quiz/resource structure
– Password protection support
– Course image support (base64)
– Per-lesson width and background customization
– Quill WYSIWYG editor integration
– Resource library with three types (text, PDF, link)
– Single quiz per lesson (3 options)
– Import/Export functionality
PLANNED FEATURES (Future Versions):
————————————
v1.1 (Proposed)
– Multiple quiz types (true/false, fill-in-blank, short answer)
– More quiz options (4-5 choices instead of just 3)
– Lesson prerequisites (must complete lesson X before Y)
– Student progress tracking structure
– Certificate generation metadata
v1.2 (Proposed)
– Course categories/tags
– Estimated completion percentage
– Difficulty rating per lesson (not just course-level)
– Course language specification
– Accessibility metadata (screen reader compatibility)
v2.0 (Proposed – Breaking Changes)
– Multi-chapter structure (group lessons into chapters)
– Conditional lesson paths (choose-your-own-adventure)
– Embedded assessments (quizzes mid-lesson, not just at end)
– Discussion prompts and reflection questions
– Graded assignments structure
BACKWARDS COMPATIBILITY COMMITMENT:
———————————–
All 1.x versions will remain backwards compatible:
– Older courses import into newer systems
– New features are additive (optional fields)
– Required fields will not change
– Existing tools continue to work
Breaking changes only in major versions (2.0, 3.0):
– Advance notice (6+ months)
– Migration tools provided
– Legacy format support for transition period
EXTENSIBILITY:
————–
Custom Fields:
Z3EDU allows custom fields for future extension.
Prefix custom fields with underscore to avoid conflicts.
Example:
“`json
{
“meta”: {
“title”: “My Course”,
“_customField”: “custom value”,
“_organization”: “My University”
}
}
“`
Standard tools will ignore custom fields.
Future versions may adopt popular custom fields into spec.
COMMUNITY CONTRIBUTIONS:
————————
We welcome:
– Course templates
– Conversion scripts (from other formats)
– Validation tools
– Editor plugins
– Example courses
Submit via:
– GitHub: [repository URL]
– Email: [contact email]
– Discord: [server invite]
SPECIFICATION UPDATES:
———————-
This specification is maintained by:
– Carl M0ICR (original author)
– Z3 Education Studio development team
– Community contributors
Last updated: February 2024
Next review: August 2024
For latest version, visit: [documentation URL]
================================================================================
END OF SPECIFICATION
================================================================================
Thank you for using Z3EDU! We hope this specification enables you to create
amazing educational content.
For support, visit: [support URL]
For examples, visit: [examples repository]
For tools, visit: [tools repository]
Happy teaching! 📚✨
================================================================================
Z3EDU JSON Specification
Shorter Specification
FILE EXTENSION: .z3edu
MIME TYPE: application/json
ENCODING: UTF-8
This specification defines the complete structure for Z3 Education Studio courses.
Use this to create courses programmatically, with AI, or in external tools.
================================================================================
COMPLETE EXAMPLE
================================================================================
{
“meta”: {
“title”: “Russian History: The October Revolution”,
“author”: “Carl”,
“version”: “1.0”,
“description”: “A comprehensive study of the 1917 Russian Revolution”,
“duration_hours”: 3,
“difficulty”: “intermediate”,
“created”: 1707926400000,
“modified”: 1707926400000,
“password”: “mypassword123”,
“image”: “data:image/png;base64,iVBORw0KGgoAAAANS…”
},
“lessons”: [
{
“id”: “lesson_intro”,
“title”: “Introduction to the October Revolution”,
“content”: “<p>The October Revolution (November 1917) was…</p><p>Key figures included…</p>”,
“duration”: 15,
“media”: “”,
“width”: 80,
“backgroundColor”: “#0f172a”,
“resources”: [“res_1707926401234”, “res_1707926402345”],
“quiz”: {
“question”: “Who led the Bolshevik Revolution?”,
“options”: [“Vladimir Lenin”, “Joseph Stalin”, “Leon Trotsky”],
“correct”: 0
}
},
{
“id”: “lesson_causes”,
“title”: “Causes of the Revolution”,
“content”: “<h2>Economic Factors</h2><p>Russia’s economy…</p><img src=’https://example.com/img.jpg’ style=’max-width:100%;’><div style=’position:relative;padding-bottom:56.25%;’><iframe src=’https://youtube.com/embed/VIDEO_ID’></iframe></div>”,
“duration”: 30,
“media”: “”,
“width”: 75,
“backgroundColor”: “#1e293b”,
“resources”: [],
“quiz”: null
}
],
“resources”: [
{
“id”: “res_1707926401234”,
“type”: “text”,
“title”: “Treaty of Brest-Litovsk”,
“content”: “The Treaty of Brest-Litovsk was a peace treaty signed on March 3, 1918…”
},
{
“id”: “res_1707926402345”,
“type”: “pdf”,
“title”: “Lenin’s April Theses”,
“url”: “https://example.com/april-theses.pdf”
},
{
“id”: “res_1707926403456”,
“type”: “link”,
“title”: “Soviet Archive Documents”,
“url”: “https://example.com/soviet-archives”
}
]
}
================================================================================
FIELD SPECIFICATIONS
================================================================================
ROOT OBJECT
———–
{
“meta”: METADATA_OBJECT (required),
“lessons”: ARRAY of LESSON_OBJECTS (required, min 1),
“resources”: ARRAY of RESOURCE_OBJECTS (optional, default [])
}
================================================================================
METADATA_OBJECT
================================================================================
{
“title”: STRING (required)
– Course title
– Min: 1 character
– Max: 200 characters
– Example: “Introduction to Quantum Physics”
“author”: STRING (optional, default “”)
– Course creator name
– Example: “Dr. Jane Smith”
“version”: STRING (optional, default “1.0”)
– Course version number
– Format: MAJOR.MINOR or semver
– Example: “1.0”, “2.3.1”
“description”: STRING (optional, default “”)
– Course description/summary
– Max: 1000 characters
– Example: “A comprehensive introduction to…”
“duration_hours”: NUMBER (optional, default 0)
– Estimated completion time in hours
– Example: 3, 12.5
“difficulty”: STRING (optional, default “beginner”)
– Course difficulty level
– Valid values: “beginner”, “intermediate”, “advanced”
“created”: NUMBER (required)
– Unix timestamp (milliseconds) of creation
– Example: 1707926400000
– Generate: Date.now() in JavaScript
“modified”: NUMBER (required)
– Unix timestamp (milliseconds) of last modification
– Example: 1707926400000
– Update on every save
“password”: STRING (required, min 6 characters)
– Course protection password
– Min length: 6 characters
– Stored in plain text (client-side security only)
– Example: “mypass123”
“image”: STRING (optional, default “”)
– Course cover image
– Format: Data URL (base64 encoded)
– Recommended size: 600x400px
– Accepted formats: PNG, JPEG
– Example: “data:image/png;base64,iVBORw0KGgo…”
}
================================================================================
LESSON_OBJECT
================================================================================
{
“id”: STRING (required, unique)
– Unique lesson identifier
– Format: “lesson_” + timestamp or UUID
– Example: “lesson_1707926400123”, “lesson_intro”
“title”: STRING (required)
– Lesson title
– Min: 1 character
– Max: 200 characters
– Example: “Chapter 1: Introduction”
“content”: STRING (required)
– Lesson content in HTML format
– Generated by Quill WYSIWYG editor
– Supports: <p>, <h1-h3>, <strong>, <em>, <u>, <strike>
– Supports: <ol>, <ul>, <li>, <a>, <span> with inline styles
– Supports: <img> tags, <iframe> for videos
– Example: “<p>Welcome to this lesson!</p>”
“duration”: NUMBER (optional, default 0)
– Estimated lesson duration in minutes
– Example: 15, 30, 45
“media”: STRING (optional, default “”)
– Legacy field for media URL
– Deprecated: use embedded content in “content” field instead
– Keep for backward compatibility
“width”: NUMBER (optional, default 80)
– Content area width as percentage
– Range: 50-100
– Step: 10
– Example: 50, 60, 70, 80, 90, 100
“backgroundColor”: STRING (optional, default “#0f172a”)
– Content area background color
– Format: Hex color code
– Example: “#0f172a”, “#1e293b”, “#ffffff”
“resources”: ARRAY of STRING (optional, default [])
– Array of resource IDs attached to this lesson
– References IDs from root-level “resources” array
– Example: [“res_1707926401234”, “res_1707926402345”]
“quiz”: QUIZ_OBJECT or null (optional, default null)
– Quiz question for this lesson
– Only one quiz per lesson supported
– Set to null if no quiz
}
================================================================================
QUIZ_OBJECT
================================================================================
{
“question”: STRING (required)
– Quiz question text
– Max: 500 characters
– Example: “What year did World War II end?”
“options”: ARRAY of STRING (required, exactly 3 items)
– Three answer options
– Example: [“1943”, “1944”, “1945”]
“correct”: NUMBER (required)
– Index of correct answer (0-indexed)
– Range: 0-2
– Example: 2 (for third option)
}
================================================================================
RESOURCE_OBJECT
================================================================================
{
“id”: STRING (required, unique)
– Unique resource identifier
– Format: “res_” + timestamp
– Example: “res_1707926401234”
“type”: STRING (required)
– Resource type
– Valid values: “text”, “pdf”, “link”
“title”: STRING (required)
– Resource title/name
– Max: 200 characters
– Example: “Treaty of Versailles Full Text”
“content”: STRING (required for type=”text”)
– Full text content of resource
– Plain text or formatted text
– Example: “The Treaty of Versailles was signed on June 28, 1919…”
“url”: STRING (required for type=”pdf” or type=”link”)
– External URL to PDF or webpage
– Must be valid URL
– Example: “https://example.com/document.pdf”
}
================================================================================
HTML CONTENT FORMATTING
================================================================================
The “content” field supports rich HTML formatting. Here are examples:
PARAGRAPHS:
<p>This is a paragraph.</p>
HEADERS:
<h1>Main Header</h1>
<h2>Subheader</h2>
<h3>Sub-subheader</h3>
TEXT FORMATTING:
<p><strong>Bold text</strong></p>
<p><em>Italic text</em></p>
<p><u>Underlined text</u></p>
<p><strike>Strikethrough text</strike></p>
COLORS:
<p><span style=”color: rgb(230, 0, 0);”>Red text</span></p>
<p><span style=”background-color: rgb(255, 255, 0);”>Highlighted</span></p>
LISTS:
<ol>
<li>First item</li>
<li>Second item</li>
</ol>
<ul>
<li>Bullet point</li>
<li>Another bullet</li>
</ul>
LINKS:
<p><a href=”https://example.com” target=”_blank”>External link</a></p>
<p><a href=”#” onclick=”Z3Education.viewResource(‘res_123’); return false;”>Resource link</a></p>
IMAGES:
<img src=”https://example.com/image.jpg” style=”max-width: 100%; border-radius: 8px; margin: 1rem 0;” alt=”Description”>
VIDEOS (YouTube):
<div style=”position: relative; padding-bottom: 56.25%; height: 0; margin: 2rem 0; border-radius: 12px; overflow: hidden; background: #000;”>
<iframe style=”position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;” src=”https://www.youtube.com/embed/VIDEO_ID” frameborder=”0″ allowfullscreen></iframe>
</div>
================================================================================
VALIDATION RULES
================================================================================
REQUIRED FIELDS:
✓ meta.title
✓ meta.created
✓ meta.modified
✓ meta.password (min 6 chars)
✓ lessons (array, min 1 item)
✓ lessons[].id (unique)
✓ lessons[].title
✓ lessons[].content
OPTIONAL FIELDS (with defaults):
○ meta.author = “”
○ meta.version = “1.0”
○ meta.description = “”
○ meta.duration_hours = 0
○ meta.difficulty = “beginner”
○ meta.image = “”
○ lessons[].duration = 0
○ lessons[].media = “”
○ lessons[].width = 80
○ lessons[].backgroundColor = “#0f172a”
○ lessons[].resources = []
○ lessons[].quiz = null
○ resources = []
CONSTRAINTS:
• lesson.width: 50 ≤ value ≤ 100, step 10
• quiz.options: exactly 3 items
• quiz.correct: 0 ≤ value ≤ 2
• resource.type: “text” | “pdf” | “link”
• All IDs must be unique within their scope
• Timestamps must be valid Unix milliseconds
================================================================================
MINIMAL VALID EXAMPLE
================================================================================
{
“meta”: {
“title”: “Quick Course”,
“created”: 1707926400000,
“modified”: 1707926400000,
“password”: “pass123”
},
“lessons”: [
{
“id”: “lesson_1”,
“title”: “Lesson One”,
“content”: “<p>Hello world!</p>”
}
]
}
================================================================================
AI COURSE GENERATION GUIDELINES
================================================================================
When generating courses with AI:
1. GENERATE UNIQUE IDs:
– Use: “lesson_” + Date.now() + random_suffix
– Example: “lesson_1707926400123”
2. RICH CONTENT:
– Use headers (<h2>, <h3>) to structure content
– Break text into paragraphs (<p>)
– Use lists for enumeration
– Add emphasis (<strong>, <em>) for key concepts
3. QUIZZES:
– Include 1 quiz per lesson (or null)
– Make questions clear and unambiguous
– Ensure exactly 3 options
– Only one correct answer
4. RESOURCES:
– Create text resources for definitions, treaties, documents
– Link to external PDFs for primary sources
– Use meaningful titles
– Reference in lessons where relevant
5. VISUAL SETTINGS:
– Use width=80 for normal lessons
– Use width=100 for image-heavy content
– Vary background colors for visual variety
6. METADATA:
– Set realistic duration_hours
– Choose appropriate difficulty level
– Write compelling description
– Always include a password
================================================================================
EXPORT/IMPORT NOTES
================================================================================
EXPORT:
– File saved with .z3edu extension
– Filename: sanitized course title + “.z3edu”
– Example: “russian-history-october-revolution.z3edu”
IMPORT:
– Must be valid JSON
– Must pass validation rules
– Password required if not present
– Created/modified timestamps preserved
COMPATIBILITY:
– Forward compatible: new fields ignored by older versions
– Backward compatible: missing optional fields use defaults
– Version field allows format evolution
================================================================================
USE CASES
================================================================================
1. MANUAL COURSE CREATION:
– Create JSON in text editor
– Import into Z3 Education Studio
– Edit with visual interface
2. AI-GENERATED COURSES:
– Use this spec with ChatGPT, Claude, etc.
– Generate complete course JSON
– Import and review
3. BATCH COURSE GENERATION:
– Script to generate multiple courses
– Template-based generation
– Automated content conversion
4. COURSE LIBRARIES:
– Share .z3edu files
– Build course repositories
– Version control with Git
5. EXTERNAL TOOLS:
– Build course authoring tools
– Convert from other formats (SCORM, xAPI)
– Integrate with LMS systems
================================================================================
VERSION HISTORY
================================================================================
v1.0 (Current):
– Initial specification
– Core lesson/quiz/resource structure
– Password protection
– Image support
– Width/background customization
================================================================================
SUPPORT & CONTACT
================================================================================
For questions about this specification:
– GitHub: [your-repo]
– Email: [your-email]
– Discord: [your-server]
For Z3 Education Studio:
– Developer: Carl M0ICR
– Project: UKBOTA/WWBOTA Education Platform
================================================================================
================================================================================
Z3 VIRTUAL UNIVERSITY – IMMERSIVE LEARNING PLATFORM
Design Specification v1.0
================================================================================
EXECUTIVE SUMMARY
—————–
Transform Z3 Education Studio into a fully immersive virtual university where
students navigate a 3D campus, attend lectures, interact with professors,
complete assignments, earn degrees, and experience authentic university life
through gamified interactive fiction.
CORE CONCEPT
————
Instead of clicking “Next Lesson,” students:
– Walk through a virtual campus (text-based navigation like Zork)
– Enter buildings (Library, Lecture Halls, Labs, Student Union, Dorms)
– Meet NPCs (Professors, classmates, staff)
– Follow a schedule (attend classes at specific times)
– Complete courses to earn credits
– Graduate with certificates/degrees
================================================================================
1. THE VIRTUAL CAMPUS
================================================================================
CAMPUS MAP STRUCTURE
——————–
The campus is navigated like a text adventure:
EXAMPLE CAMPUS LAYOUT:
[LIBRARY]
|
[SCIENCE BLDG]—[QUAD]—[LECTURE HALL A]
|
[STUDENT UNION]
|
[DORMITORY]——[CAMPUS GATE]——[ADMINISTRATION]
Each location is a “room” with:
– Full description (architecture, atmosphere, people present)
– Exits to other locations
– Interactive elements (bulletin boards, NPCs, objects)
– Time-specific events (lectures only during class hours)
LOCATION TYPES:
1. LECTURE HALLS
– Where classes happen
– Multiple lecture rooms (A, B, C for different subjects)
– Professor’s podium, student seating
– Attend lectures to learn content
– Take notes, ask questions
2. LIBRARY
– Research materials
– Study carrels for focused work
– Reference books on subjects
– Librarian NPC for help finding resources
– Complete reading assignments here
3. STUDENT UNION
– Social hub
– Bulletin board with announcements
– Meet classmates
– Study groups form here
– Coffee shop for breaks
4. DORMITORY
– Student’s personal room
– Save progress, rest between classes
– Store items (textbooks, notes)
– Roommate NPC for conversations
5. ADMINISTRATION BUILDING
– Registrar’s office (enroll in courses)
– Dean’s office (view transcript, graduation status)
– Advisor’s office (get guidance)
– Financial aid office (scholarships, achievements)
6. LABORATORIES
– Hands-on learning spaces
– Science experiments, computer labs, language labs
– Interactive assignments
– Equipment to use
7. QUAD (Campus Center)
– Central meeting point
– Events and activities
– Notice boards with campus news
– Connect to all major buildings
8. PROFESSOR OFFICES
– Office hours with instructors
– Get help with coursework
– Discuss grades
– Personal mentorship
================================================================================
2. THE ACADEMIC SYSTEM
================================================================================
COURSE ENROLLMENT
—————–
Students don’t just “start a course” – they ENROLL:
1. Visit Administration Building
2. Talk to Registrar NPC
3. View course catalog
4. Choose courses (up to 4 per semester)
5. Receive course schedule
EXAMPLE ENROLLMENT DIALOGUE:
> TALK TO REGISTRAR
Registrar: “Welcome! Ready to register for Spring semester? We have
excellent courses available. What’s your area of interest?”
[OPTIONS]
A) History
B) Science
C) Literature
D) View full catalog
> A
Registrar: “Wonderful! Here are our History offerings:
HIST 101 – Ancient Civilizations (3 credits)
Professor Chen | MWF 10:00-11:00 | Lecture Hall A
HIST 205 – Russian Revolution (4 credits)
Professor Volkov | TTh 13:00-15:00 | Lecture Hall B
HIST 310 – Military History (3 credits)
Professor Wade | MWF 14:00-15:00 | Lecture Hall C
Which would you like to enroll in?”
COURSE STRUCTURE
—————-
Each course has:
– LECTURES (attend in person at lecture hall)
– READINGS (complete in library)
– ASSIGNMENTS (submit to professor)
– EXAMS (scheduled events)
– CREDITS (earned on completion)
EXAMPLE COURSE: Russian History 1700-1991
Week 1: Imperial Russia
Monday: Lecture – “Peter the Great” (Lecture Hall B, 13:00)
Tuesday: Reading – Primary sources (Library)
Wednesday: Lecture – “Catherine’s Expansion” (Lecture Hall B, 13:00)
Thursday: Office Hours – Professor Volkov available
Friday: Assignment Due – Essay on reforms
Week 2: Revolutionary Period
[continues…]
CREDIT SYSTEM
————-
– Each course worth 3-4 credits
– Need 120 credits to graduate
– Major requires 40 credits in subject
– Electives fill remaining credits
GPA TRACKING
————
– Assignments graded A through F
– Exams contribute to final grade
– View transcript in Dean’s office
– Dean’s List for 3.5+ GPA
================================================================================
3. THE SCHEDULE SYSTEM
================================================================================
TIME PROGRESSION
—————-
Virtual university operates on a schedule:
DAILY SCHEDULE:
08:00-09:00 Morning (wake up, breakfast)
09:00-12:00 Morning classes
12:00-13:00 Lunch break
13:00-16:00 Afternoon classes
16:00-18:00 Study time, office hours
18:00-19:00 Dinner
19:00-22:00 Evening study, social time
22:00-08:00 Night (sleep, save progress)
WEEKLY SCHEDULE:
Monday-Friday: Classes and studying
Saturday: Free exploration, catch-up work
Sunday: Preparation for next week
SEMESTER CALENDAR:
Week 1-2: Enrollment and orientation
Week 3-6: Regular coursework
Week 7: Midterm exams
Week 8-12: Advanced topics
Week 13-14: Final exams
Week 15: Break before next semester
TIME MECHANICS:
– Time advances when you complete activities
– “WAIT” command to skip to next event
– Can’t attend lecture if you’re late
– Office hours only available at set times
EXAMPLE TIME SYSTEM:
> LOOK
You are in the Quad. It’s Monday, 09:45. Students hurry to their 10:00
classes. You have HIST 101 in Lecture Hall A at 10:00.
> GO NORTH
You walk to Lecture Hall A. It’s now 09:50. Students are filing in.
> ENTER
You take a seat. Professor Chen begins the lecture at 10:00.
================================================================================
4. NPC PROFESSORS & CLASSMATES
================================================================================
PROFESSOR CHARACTERS
——————–
Each professor has:
– Personality (stern, friendly, eccentric, inspiring)
– Office hours schedule
– Dialogue trees for questions
– Grading tendencies
– Special knowledge to share
EXAMPLE PROFESSORS:
PROFESSOR ELENA VOLKOV (Russian History)
Age: 52, Specialization: Soviet Era
Personality: Passionate, demanding, brilliant
Office: History Building, Room 304
Hours: Tuesday/Thursday 15:00-17:00
Dialogue Topics:
– Course content (ask about specific events)
– Assignment help (get hints)
– Historical debates (deeper discussions)
– Career advice (unlock history career paths)
> TALK TO PROFESSOR VOLKOV
Volkov: “Ah, come in! Discussing the October Revolution, yes? The Western
narrative often oversimplifies. Let me show you something…”
[She pulls out a primary source document]
“This is Trotsky’s account. Notice the differences from Lenin’s version?
History is written by winners, but we must read between the lines.”
[OPTION: Ask about midterm | Ask about thesis topic | Thank and leave]
CLASSMATE NPCs
————–
Fellow students provide:
– Study group opportunities
– Social interaction
– Competition and motivation
– Tips and hints
EXAMPLE CLASSMATES:
JAMES CARTER (Computer Science Major)
Personality: Helpful, nerdy, always in library
Found: Library study carrels, Student Union
Can: Help with research, form study groups, share notes
SOFIA MARTINEZ (Pre-Med)
Personality: Competitive, organized, ambitious
Found: Science labs, cafeteria
Can: Quiz you on material, study partner, friendly rivalry
Interaction Example:
> TALK TO JAMES
James looks up from his laptop. “Oh hey! Studying for Volkov’s midterm?
That essay question is brutal. Want to compare notes? I’ve got some good
material on the causes of revolution.”
[OPTION: Study together | Decline politely | Ask about other courses]
STAFF NPCs
———-
Support characters:
LIBRARIAN – Helps find resources
REGISTRAR – Handles enrollment
DEAN – Tracks progress, graduation
ADVISOR – Recommends courses
CAFETERIA WORKER – Provides sustenance (and gossip)
SECURITY GUARD – Campus lore and shortcuts
================================================================================
5. IMMERSIVE LEARNING MECHANICS
================================================================================
ATTENDING LECTURES
——————
Instead of “click next lesson”:
> ENTER LECTURE HALL B
You take your usual seat in the middle row. Professor Volkov stands at the
podium, a map of 1917 Russia projected behind her.
Volkov: “Today we examine the February Revolution. The Romanov dynasty, 300
years of rule, collapsed in days. Why? Let’s start with the immediate causes…”
[LECTURE CONTENT DISPLAYED]
While reading:
– Can TAKE NOTES (saves to inventory)
– Can ASK QUESTION (triggers dialogue)
– Can LOOK AROUND (see other students’ reactions)
After lecture:
– Notes added to inventory
– Attendance marked
– Can discuss with classmates leaving hall
LIBRARY RESEARCH
—————-
Reading assignments become exploration:
> GO TO LIBRARY
The university library looms before you, its marble columns supporting a
grand entrance. Students stream in and out with armfuls of books.
> ENTER
The vast reading room stretches before you. Rows of wooden tables, towering
bookshelves. The smell of old paper and coffee. Soft murmurs and turning pages.
> TALK TO LIBRARIAN
Librarian: “Looking for something specific? We have extensive collections.”
> ASK ABOUT RUSSIAN REVOLUTION PRIMARY SOURCES
Librarian: “Ah yes, third floor, Eastern European History section. Look for
the red volumes – those are translated documents. The Trotsky memoirs are
particularly illuminating.”
> GO UP
> EXAMINE RED VOLUMES
[Display reading material with TAKE NOTES option]
ASSIGNMENTS & EXAMS
——————-
Completing work feels meaningful:
ASSIGNMENTS:
– Receive from professor during lecture
– Research in library
– Write in your dorm room
– Submit to professor’s office
– Receive graded feedback
EXAMPLE ASSIGNMENT:
Professor Volkov hands you a sheet: “Essay due Friday. Compare Lenin and
Trotsky’s accounts of October Revolution. 1000 words minimum. Use at least
three primary sources.”
[Task added to Student Planner]
> GO TO LIBRARY
> RESEARCH LENIN MEMOIRS
> TAKE NOTES
> GO TO DORM
> WRITE ESSAY
[Submit dialogue/quiz on comprehension]
> GO TO PROFESSOR’S OFFICE
> SUBMIT ASSIGNMENT
[Two days later…]
You find your graded essay in your mailbox. Red ink marks specific points.
Grade: A-
Comments: “Excellent analysis of the differences. However, you could explore
the political motivations behind their conflicting narratives more deeply.
See me during office hours if you want to discuss.”
EXAMS:
– Scheduled events (must attend on time)
– Proctored in exam hall
– Mix of multiple choice, short answer, essay
– Timed (can’t leave and return)
– Results impact GPA
================================================================================
6. PROGRESSION & ACHIEVEMENTS
================================================================================
CREDIT ACCUMULATION
——————-
Track progress visually:
> CHECK TRANSCRIPT
[Display]
=====================================
UNIVERSITY TRANSCRIPT
Student: [Player Name]
Major: History
Minor: Political Science
=====================================
Completed Courses:
HIST 101 – Ancient Civilizations A 4 credits
HIST 205 – Russian Revolution A- 4 credits
POLS 101 – Intro to Politics B+ 3 credits
Total Credits: 11/120
Current GPA: 3.7
Status: Sophomore, Good Standing
=====================================
ACHIEVEMENTS SYSTEM
——————-
Gamify learning:
ACADEMIC ACHIEVEMENTS:
🏆 Dean’s List (GPA 3.5+)
📚 Bookworm (Complete 10 reading assignments)
🎓 Perfect Attendance (Never miss a class)
💯 Ace (Score 100% on exam)
🔍 Research Master (Use library 25 times)
✍️ Prolific Writer (Submit 20 assignments)
SOCIAL ACHIEVEMENTS:
👥 Popular (Talk to 15 different NPCs)
☕ Caffeine Addict (Visit student union 30 times)
🤝 Study Buddy (Complete 5 group studies)
🗣️ Office Hours Regular (Visit professors 10 times)
EXPLORATION ACHIEVEMENTS:
🗺️ Campus Explorer (Visit every location)
🌙 Night Owl (Study past midnight)
📅 Punctual (Arrive early to 10 classes)
DEGREE PROGRESSION
——————
Visual degree completion:
> CHECK DEGREE PROGRESS
[Display]
=====================================
BACHELOR OF ARTS – HISTORY
=====================================
Core Requirements: [████████░░] 80%
HIST 101 ✓
HIST 205 ✓
HIST 301 ▢
HIST 401 ▢
Major Electives: [████░░░░░░] 40%
HIST 310 ✓
HIST 320 ▢
HIST 330 ▢
General Education: [██████████] 100%
Writing ✓
Math ✓
Science ✓
Credits: 72/120
Semesters Remaining: 4
Projected Graduation: Spring 2027
=====================================
GRADUATION CEREMONY
——————-
Grand finale:
After completing 120 credits with passing grades:
> GO TO ADMINISTRATION
Dean: “Congratulations! You’ve completed all degree requirements. Your
graduation ceremony is scheduled for Saturday at 14:00 in the Main Quad.
Don’t be late!”
[Saturday, 14:00, Main Quad]
Hundreds of students in caps and gowns fill folding chairs. Proud families
watch from the lawn. The University President stands at the podium.
President: “It is my honor to confer upon you the degree of Bachelor of Arts
in History, with all the rights and privileges thereunto appertaining…”
[CERTIFICATE GENERATED – PDF download]
[ACHIEVEMENT UNLOCKED: Graduate]
[Final statistics displayed]
================================================================================
7. STUDENT LIFE SIMULATION
================================================================================
DORMITORY SYSTEM
—————-
Your room is home base:
> ENTER DORM ROOM
A small but cozy space. Your desk cluttered with textbooks and notes. Posters
on the walls. Your laptop on the bed. Roommate Alex is at their desk.
> INVENTORY
You are carrying:
– Backpack
– Notebook (HIST 205 notes)
– Laptop
– Student ID card
– Cafeteria meal card ($47.50 remaining)
> TALK TO ALEX
Alex: “Hey! How was Volkov’s class? I heard the midterm is going to be rough.”
[Roommate provides tips, social interaction, study reminders]
> STUDY
You spend 2 hours reviewing your notes. [Knowledge increased]
> SLEEP
You rest well. [Game saved. Time advances to next day]
SOCIAL SPACES
————-
Hang out, not just study:
STUDENT UNION:
– Coffee shop (buy snacks, chat)
– Game room (play pool, decompress)
– Notice boards (side quests, events)
– Study lounges (meet other students)
CAFETERIA:
– Daily meals (maintain energy)
– Overhear conversations (hints, rumors)
– Social dynamics (cliques, friendships)
CAMPUS EVENTS:
– Guest lectures (bonus content)
– Club meetings (join history society)
– Sports games (school spirit)
– Movie nights (social time)
STUDENT NEEDS SYSTEM
——————–
Maintain balance:
ENERGY: Study too long, get tired. Rest in dorm or cafeteria.
HUNGER: Need to eat meals. Low hunger = poor concentration.
STRESS: Exams and deadlines increase stress. Manage with breaks.
SOCIAL: Interact with NPCs. Isolation = reduced motivation.
> CHECK STATUS
[Display]
Energy: [████████░░] 80%
Hunger: [██████░░░░] 60% (Should eat soon)
Stress: [█████░░░░░] 50% (Midterms approaching)
Social: [███████░░░] 70% (Doing well)
Tip: Visit the cafeteria or take a study break.
================================================================================
8. MULTI-COURSE MANAGEMENT
================================================================================
JUGGLING CLASSES
—————-
Simulate real university load:
EXAMPLE SEMESTER SCHEDULE:
Monday:
09:00 – HIST 205 (Russian Revolution)
11:00 – POLS 201 (Comparative Politics)
14:00 – Free time
Tuesday:
10:00 – PHIL 101 (Intro to Philosophy)
13:00 – HIST 205 Office Hours (optional)
Wednesday:
09:00 – HIST 205
11:00 – POLS 201
15:00 – Library research time
Thursday:
10:00 – PHIL 101
14:00 – Assignment due (HIST essay)
Friday:
09:00 – HIST 205
11:00 – POLS 201
13:00 – Study group (optional)
WEEKLY PLANNER
————–
Track everything:
> CHECK PLANNER
[Display]
=====================================
WEEK 7 – MIDTERM WEEK
=====================================
MONDAY:
✓ Attend HIST 205 lecture
✓ Attend POLS 201 lecture
▢ Review PHIL notes
! HIST midterm on Wednesday!
TUESDAY:
▢ PHIL lecture
▢ HIST office hours (get exam tips)
▢ Library – review Russian Revolution
WEDNESDAY:
! HIST 205 MIDTERM – 09:00 sharp!
▢ POLS lecture
▢ Celebrate survival
Assignments Due This Week:
! POLS essay (Thursday 23:59)
▢ PHIL reading response (Friday)
Study Group Meetings:
– Tuesday 19:00 (James, Sofia, Marcus)
=====================================
PRIORITIZATION
————–
Choices matter:
It’s Tuesday evening. You have:
– HIST midterm tomorrow (need to study)
– POLS essay due Thursday (barely started)
– Study group meeting in 1 hour
– Low energy (should rest)
What do you do?
A) Study for HIST (safer choice)
B) Work on POLS essay (riskier but necessary)
C) Attend study group (social, might help both)
D) Sleep (recover energy for tomorrow)
Consequences:
– Wrong choice = worse grade
– Right balance = success
– Teaches time management
================================================================================
9. TECHNICAL IMPLEMENTATION
================================================================================
HYBRID ARCHITECTURE
——————-
Combines Z3 Adventure + Z3 Education:
FROM Z3 ADVENTURE STUDIO:
– Room/location system
– NPC dialogue trees
– Inventory management
– Object interactions
– Time/state tracking
FROM Z3 EDUCATION STUDIO:
– Lesson content (lectures)
– Quiz system (exams)
– Progress tracking (credits, GPA)
– Course structure
NEW SYSTEMS:
– Schedule/calendar
– Enrollment/registration
– Multi-course juggling
– Needs system (energy, hunger, stress)
– Achievement tracking
– Certificate generation
DATA STRUCTURE EXAMPLE:
{
“university”: {
“name”: “Z3 University”,
“locations”: [
{
“id”: “quad”,
“name”: “Campus Quad”,
“description”: “…”,
“exits”: {“n”: “library”, “s”: “union”},
“npcs”: [“student_james”, “guard_mike”],
“time_events”: {
“weekday_morning”: “Students hurry to class”,
“weekend”: “Groups playing frisbee”
}
}
],
“courses”: [
{
“id”: “hist_205”,
“code”: “HIST 205”,
“name”: “Russian Revolution”,
“credits”: 4,
“professor”: “npc_volkov”,
“location”: “lecture_hall_b”,
“schedule”: {
“monday”: “13:00-15:00”,
“wednesday”: “13:00-15:00”
},
“lessons”: […],
“assignments”: […],
“exams”: […]
}
],
“npcs”: [
{
“id”: “npc_volkov”,
“name”: “Professor Elena Volkov”,
“role”: “professor”,
“subject”: “Russian History”,
“office”: “history_304”,
“office_hours”: “Tuesday 15:00-17:00”,
“personality”: “passionate_demanding”,
“dialogue”: {…}
}
],
“player”: {
“name”: “…”,
“major”: “History”,
“credits”: 72,
“gpa”: 3.7,
“current_semester”: 6,
“enrolled_courses”: [“hist_205”, “pols_201”],
“completed_courses”: […],
“inventory”: […],
“location”: “dorm_room”,
“status”: {
“energy”: 80,
“hunger”: 60,
“stress”: 50,
“social”: 70
},
“schedule”: {…}
}
}
}
================================================================================
10. USER EXPERIENCE FLOWS
================================================================================
NEW STUDENT ORIENTATION
———————–
Day 1: Welcome to University!
> START
You stand at the iron gates of Z3 University. Beyond, tree-lined paths lead
to ivy-covered buildings. Students with backpacks walk purposefully. A sign
reads: “New Student Orientation – Report to Administration Building”
> GO NORTH
You walk through the gates onto campus. The path leads to a large quad with
a fountain in the center.
[LOCATION: Campus Quad]
> LOOK
The heart of campus. Four paths lead to different buildings. A bronze statue
of the university founder stands by the fountain. Students sit on benches,
chatting and studying.
> EXAMINE STATUE
Inscription: “Founded 1887 – Knowledge is Freedom”
> GO NORTH
[LOCATION: Administration Building]
A grand old building with marble columns. Through the door, you see a
reception desk.
> ENTER
[LOCATION: Administration Lobby]
Receptionist: “Welcome! You must be here for orientation. The registrar is
expecting you. Office 101, down the hall.”
> GO EAST
> ENTER OFFICE 101
[LOCATION: Registrar’s Office]
The registrar looks up from her desk. “Ah, new student! Let’s get you
registered. First, I need some information…”
[Character creation: Choose name, major, minor]
“Excellent! Now, let me explain how university works here…”
[Tutorial on:
– Navigating campus
– Attending lectures
– Using the library
– Completing assignments
– Managing your schedule
]
“Here’s your course catalog. Choose your first semester classes…”
[First enrollment]
“Perfect! Classes start Monday. Here’s your schedule and campus map. Your
dorm room is in the South Dormitory. Need anything else, just ask!”
[Player now free to explore campus before classes start]
TYPICAL DAY FLOW
—————-
Monday Morning:
> WAKE UP
[8:00 AM, Dorm Room]
You wake to sunlight streaming through the window. Alex is already up,
making coffee.
Alex: “Morning! Don’t forget, Volkov’s lecture is at 9. Heard she’s tough
on tardiness.”
> CHECK SCHEDULE
Today’s Schedule:
09:00 – HIST 205 Lecture (Lecture Hall B)
11:00 – POLS 201 Lecture (Lecture Hall A)
14:00 – Free time
19:00 – Study group (optional)
> INVENTORY
Backpack, Laptop, Student ID, Meal Card, Notebooks
> GO CAFETERIA
[8:30 AM, Cafeteria]
Breakfast smells fill the air. You grab a tray.
> BUY BREAKFAST
[$5 deducted from meal card. Energy +20%]
> EAT
[8:45 AM]
Feeling refreshed. You see James at a nearby table.
> TALK TO JAMES
James: “Hey! Ready for Volkov’s lecture? I heard today’s about Lenin’s rise
to power. Should be intense.”
> GO TO LECTURE HALL B
[8:55 AM]
You arrive 5 minutes early. Good thing – Volkov is already setting up her
presentation. You take a seat.
[9:00 AM – LECTURE BEGINS]
[Lecture content displayed with interactive elements]
[10:00 AM – LECTURE ENDS]
Professor Volkov: “Remember, your essays are due Friday. Use primary sources!”
> GO TO LIBRARY
[10:15 AM]
Time to start that essay research…
[Continue day…]
EXAM DAY EXPERIENCE
——————-
> WAKE UP
[Wednesday, 8:00 AM]
You slept terribly. Today is the HIST 205 midterm. You’ve studied, but still
nervous.
> CHECK STATUS
Energy: [██████░░░░] 60% (Worried about exam)
Stress: [████████░░] 80% (High – major test)
> GO TO CAFETERIA
You’re too nervous to eat much. [Energy +10%]
> GO TO LECTURE HALL B
[8:45 AM]
Other students file in, looking equally anxious. Professor Volkov hands out
blue books. “You have 90 minutes. Begin when ready.”
[EXAM BEGINS]
[Display exam questions – mix of multiple choice and essay]
Question 1: Which event directly precipitated the February Revolution?
A) Rasputin’s assassination
B) Bread riots in Petrograd
C) Military defeats in WWI
D) Bolshevik agitation
> B
Correct! [+10 points]
[Continue through exam…]
Essay Question: Compare and contrast the February and October Revolutions.
Discuss the role of different social classes in each.
[Text entry or dialogue-based response system]
[EXAM ENDS]
You hand in your blue book. Volkov: “Results posted by Friday.”
[Friday]
> CHECK MAILBOX
Your exam is back. Grade: 92/100 (A-)
Comments: “Excellent understanding of class dynamics. Minor date error in
question 5. Overall strong performance.”
[Stress decreases, GPA updated]
================================================================================
11. COURSE CREATION FOR DESIGNERS
================================================================================
For course creators, the system becomes richer:
INSTEAD OF:
– Lesson 1: Title + Content + Quiz
CREATE:
– Lecture 1: In-person event at specific location/time
– Reading 1: Library resource students must find
– Assignment 1: Task requiring research and submission
– NPC Interaction: Professor office hours for help
– Exam: Proctored event testing multiple lessons
EXAMPLE COURSE DESIGN:
Course: Russian Revolution (HIST 205)
Professor: Elena Volkov
Location: Lecture Hall B
Schedule: MW 13:00-15:00
Week 1: Imperial Russia
Monday Lecture: “The Romanov Dynasty”
– Location: Lecture Hall B, 13:00
– Content: [Full lecture text]
– Trigger: Professor discusses 300 years of rule
– Interactive: Can ask about Rasputin
Required Reading: “Memoirs of Nicholas II”
– Location: Library, 3rd Floor, Section E
– Object: Red leather-bound volume
– Notes: Take notes on abdication
Assignment: Short essay (500 words)
– Due: Friday 23:59
– Submit to: Professor’s office or email
– Grading: Rubric checks key points
Office Hours: Tuesday 15:00-17:00
– Location: History Building, Room 304
– Help available: Essay guidance, clarifications
Week 2: Revolution Begins
[continues…]
Final Exam: Comprehensive
– Date: Week 14, Monday 13:00
– Format: Multiple choice + 2 essays
– Study resources: All lecture notes + 5 key readings
This creates a real university experience!
================================================================================
12. IMPLEMENTATION ROADMAP
================================================================================
PHASE 1: FOUNDATION (Core Campus)
– Campus navigation (5-10 key locations)
– Basic schedule system
– Single course experience
– Professor NPC (one)
– Simple inventory
PHASE 2: ACADEMIC DEPTH
– Multiple courses simultaneously
– Credit system and GPA
– Assignments and grading
– Library research system
– Exam mechanics
PHASE 3: SOCIAL LAYER
– Classmate NPCs
– Study groups
– Dormitory system
– Social stats
– Campus events
PHASE 4: PROGRESSION
– Multi-semester structure
– Degree requirements tracking
– Achievement system
– Graduation ceremony
– Certificate generation
PHASE 5: POLISH & IMMERSION
– Rich location descriptions
– Time-based events
– Seasonal changes
– Easter eggs and secrets
– Replayability (different majors)
================================================================================
END OF SPECIFICATION
================================================================================
This is the Virtual University vision: a fully immersive educational experience
that feels like attending a real university, but through interactive fiction.
Students don’t just consume content – they LIVE the university experience.
NEXT STEPS:
1. Approve this design
2. Decide on implementation approach (from scratch or heavy Z3 Studio modification)
3. Build prototype (single course, basic campus)
4. Expand to full system
Ready to build the Virtual University? 🎓