Lucida-flow Studio & QOrigin Hub

Documentação Oficial para Programadores | Versão 1.0
Copyright © 2026 QOrigin Hub Tecnológica

O ecossistema QOrigin é composto por duas partes fundamentais: Lucida-Flow, uma linguagem de programação estruturada, tipada dinamicamente e orientada a objetos; e o Lucida-flow Studio, um IDE de grau industrial com renderização nativa, preenchimento automático (auto-completion) e compilação direta para executáveis (.exe).

1. O Ambiente: Lucida-flow Studio

O IDE foi concebido para um fluxo de trabalho contínuo (Flow), isolando a interface gráfica da execução de código para prevenir falhas (crashes).

Funcionalidades da Interface

  • Espaços de Trabalho (Workspaces): Gestão de projetos em pastas com uma árvore de ficheiros (QTreeView). O estado do workspace (ficheiros abertos) é guardado automaticamente em .qorigin_workspace.json.
  • Motor de Temas Dinâmico: Personalização de cores em tempo real (Cyberpunk, Matrix, Tron, Alert, Void) e controlo de escala do tipo de letra para acessibilidade.
  • IntelliSense: Sugestões de código em tempo real, abrangendo todas as palavras reservadas, funções integradas e módulos da biblioteca standard (ex: math3d, qbit, gui).

Atalhos de Execução e Compilação

Atalho / Botão Ação Descrição
F5 Executar na Consola Executa o código em modo de texto no terminal integrado. Suporta entradas interativas (read).
F6 Executar Interface Gráfica Inicia o renderizador de UI numa thread paralela isolada.
Shift + F5 Sniper (Parar) Aborta forçadamente qualquer execução em curso (ciclo infinito ou falha).
Ctrl + S Guardar Guarda o documento atual.
Botão ⚙ Compilar Exporta o projeto atual para um Executável Windows (.exe), permitindo escolher entre o modo Consola ou Janela Oculta (GUI).

2. A Linguagem: Lucida-Flow

2.1. Variáveis e Tipagem Híbrida

A linguagem possui tipagem forte mas alocação dinâmica. O operador + está sobrecarregado para concatenar strings de forma automática e segura.
Tipos suportados: int, float, string, bool, null, list (Arrays), dict (Dicionários) e tuple.

let name = "Prism Engine"
const version = 1.0
let active = true

// O compilador compreende e converte números em strings automaticamente
print("A " + name + " está na versão " + version)

2.2. Estruturas de Dados

Suporte nativo para listas (Arrays) e dicionários com métodos integrados.

let enemies = ["Orc", "Troll", "Goblin"]
enemies.append("Dragon")

let config = { "resolution": "1080p", "vsync": true }

2.3. Controlo de Fluxo (Condicionais e Ciclos)

A linguagem usa when em vez do tradicional "if", trazendo uma semântica orientada a eventos.

// A preparar dados para o exemplo
let energy = 15
let enemies = ["Orc", "Goblin", "Troll"]
let active = false

define process critical_alert() {
    print("Alerta: Energia crítica!")
}

define process maintain_route() {
    print("Sistemas normais. Rota mantida.")
}

// Condicionais
when (energy < 20) {
    critical_alert()
} otherwise {
    maintain_route()
}

// Ciclo - Para Cada
for each enemy in enemies {
    print("Inimigo detetado: " + enemy)
}

// Ciclo - Enquanto
while (active == true) {
    print("Sistema ativo...")
    active = false // Previne um ciclo infinito no exemplo
}

2.4. Funções (Processos)

Os blocos de código reutilizáveis são definidos como process.

// A preparar dados
let attack = 50
let defense = 20

define process calculate_damage(attack, defense) {
    let final_damage = attack - defense
    print("Dano causado: " + final_damage)
}

// Chamar o processo
calculate_damage(attack, defense)

2.5. Programação Orientada a Objetos (POO)

A Lucida-Flow suporta encapsulamento e instanciação de objetos usando a palavra-chave type.

// Na Lucida-Flow, pode usar Dicionários para criar entidades dinâmicas
let player = {
    "name": "Marco",
    "hp": 100
}

// Criamos um processo que recebe a entidade e altera os seus dados
define process take_damage(target, amount) {
    target["hp"] = target["hp"] - amount
    print(target["name"] + " sofreu dano! HP Atual: " + target["hp"])
}

// Testar a lógica de combate
print("A iniciar a batalha...")
take_damage(player, 15)
take_damage(player, 25)

2.6. Resiliência: Try/Catch/Finally

Sistema avançado de captura de exceções baseado em Registos de Ativação. Evita falhas (crashes) na aplicação ao lidar com erros em tempo de execução.

// A preparar uma simulação para o exemplo
define process connect_database() {
    print("A ligar à base de dados...")
    // A lógica de conexão que poderia falhar iria aqui
}

// Exemplo de Tratamento de Erros (Try / Catch / Finally)
try {
    connect_database()
    print("Operação concluída com sucesso!")
} catch (error: Exception) {
    print("Falha detetada: " + error)
} finally {
    print("Bloco de execução terminado. A limpar a memória...")
}

3. Biblioteca Standard

A Lucida-Flow vem com as baterias incluídas. Abaixo estão os módulos nativos (acedidos via import "nome_modulo" as alias).

Módulo: gui (Interface Gráfica e Canvas)

Responsável por renderizar o sistema de janelas nativo do sistema operativo.

Função Parâmetros Descrição
create_window id, resolution Instancia a janela principal (ex: "App", "800x600").
create_label id, text Cria texto simples no ecrã.
create_button id, text, callback Cria um botão que aciona um process ao ser clicado.
create_input id Cria uma caixa de introdução de texto de linha única.
create_text_box id Cria um bloco de texto multilinha.
create_slider id, min, max Cria um controlo deslizante numérico.
create_checkbox id, text Cria uma caixa de verificação booleana (0 ou 1).
create_list id Cria um componente de lista com deslocamento (Componente Dinâmico).
create_canvas id, w, h, color Cria um Canvas para renderização 2D.
draw_line id, x1, y1, x2, y2, color Desenha uma linha no Canvas 2D.
bind_mouse_event id, event, callback Captura cliques e movimento do rato, passando X e Y.
schedule_update ms, callback Cria um ciclo recursivo assíncrono (Temporizador).

Outros Módulos do Sistema

  • math e math3d: Cálculos avançados e simulação vetorial. (pi, sqrt, sum, dist2d, dot, cross, normalize).
  • fs (Sistema de Ficheiros): write, read, exists, delete.
  • json: parse, stringify.
  • time & datetime: now, format, parse.
  • web: get (Consumo de API externa).
  • Jogos e Simulação (media & dice): dice.d6, dice.roll_between (RNG Nativo). Sistema completo de áudio (load, play, pause, stop).
  • Simulação Quântica (qbit): Portas lógicas quânticas nativas. (h_gate, x_gate, measure).

4. Exemplo Principal: O Poder da Lucida-Flow

Este exemplo demonstra a criação de uma interface gráfica complexa, utilizando ciclos e manipulação de componentes dinâmicos de forma limpa e concisa.

import "gui" as screen
import "time" as clock

screen.create_window("Painel da Prism Engine", "600x400")
screen.create_label("title", "INSPETOR DE ENTIDADES")

// Preenche uma lista dinamicamente
let entities = ["Player", "Enemy_1", "Final_Boss", "Physics_Box"]
screen.create_list("object_list")

// Ciclo corrigido: sem parênteses
for each obj in entities {
    screen.add_list_item("object_list", obj)
}

screen.create_button("btn_analyze", "INSPECIONAR", "analyze")
screen.create_result_label("log", "A aguardar...")

define process analyze() {
    let target = screen.get_list_selection("object_list")
    let time_now = clock.now()
    
    when (target != "") {
        screen.change_text("log", "[" + time_now + "] A inspecionar: " + target)
    } otherwise {
        screen.change_text("log", "Erro: Nenhuma entidade selecionada.")
    }
}

// Inicia a renderização
screen.start_loop()
QOrigin Hub - A desenvolver as fundações do amanhã, hoje.

© 2026 QOrigin Hub Tecnológica. Todos os direitos reservados.