Skip to content

Manual técnico para usuarios

Jump to bottom
Rodrigo Alfonso edited this page Mar 31, 2020 · 3 revisions

Estructura de un proyecto .gbp

Los archivos de proyecto .gbp son en realidad archivos zip encubiertos con el siguiente contenido:

Nombre de archivo Uso
content.gbs y/o content.gbk Código del estudiante (texto y bloques)
backpack.gbs y/o backpack.gbk Biblioteca del estudiante (texto y bloques)
extra.gbs Biblioteca del docente
meta.yml Configuración del proyecto
assets/attires/{nombre}/config.yml Asociaciones de la vestimenta {nombre}
assets/attires/{nombre}/*.{png-jpg} Imágenes de la vestimenta {nombre}
assets/boards/*.gbb Tableros iniciales posibles
assets/solutions/{nombre}.{gbs-gbk} Solución al ejercicio
description.md Consigna

Estructura vieja (DEPRECADA)

La estructura vieja posee algunas diferencias:

Nombre de archivo Uso
projectName.gbs y/o projectName.gbjs Código del estudiante (texto y bloques)
projectName.gbl y/o projectName.gbjl Biblioteca del estudiante (texto y bloques)
projectName.gbt Biblioteca del docente
projectName.json Configuración del proyecto
*.gbb Tablero
attires/{nombre}/config.json Asociaciones de la vestimenta {nombre}
attires/{nombre}/*.{png-jpg} Imágenes de la vestimenta {nombre}
description.md Consigna
image.png Imagen de 300x300 para portada

Formatos

Formato *.gbs

Es código gobstones en texto plano.

Formato *.gbk

Es una representación en XML del workspace de Blockly. Es generada automáticamente por Blockly, y suele ser dependiente de versión.

Formato *.gbb

Representa a un tablero con el siguiente formato:

GBB/1.0
size 9 9
cell 0 0 Azul 0 Negro 0 Rojo 0 Verde 1
cell 1 2 Rojo 23
head 1 2

Formato meta.yml

Contiene metadatos del proyecto en formato YAML. Consta de las siguientes claves:

Clave Tipo Descripción
name String Nombre del proyecto
library Object Opciones de biblioteca (ignoradas en modo bloques)
library.visible Boolean Mostrar botón de biblioteca
source Object Opciones de sección de código
source.visible Boolean Mostrar código por default
source.percentage Number Porcentaje de visibilidad de la sección de código
board Object Opciones de sección de tablero
board.active Number Número de tablero seleccionado por default
board.initial_board_source selected o random Determina el modo de selección de tablero para cada ejecución
board.visible_edition Boolean Mostrar la sección de edición
board.collapse_toolbox Boolean Mostrar inicialmente colapsada la sección de edición
board.user_permissions Object Permisos
board.user_permissions.can_change_initial_board Boolean Puede cambiar de tablero inicial, y si tiene can_edit_board puede agregar y quitar tableros
board.user_permissions.can_change_initial_board_source Boolean Puede cambiar la fuente de tablero inicial (random o seleccionado)
board.user_permissions.can_edit_board Boolean Puede editar el tablero inicial
board.user_permissions.can_view_size_section Boolean Puede ver la sección de tamaño (default: true)
board.user_permissions.can_view_attire_section Boolean Puede ver la sección de vestimentas (default: true)
execution_speed Object Determina la velocidad de ejecución
execution_speed.active low, medium, high, superhigh o instantaneous Velocidad de ejecución por default
execution_speed.user_permissions Object Permisos
execution_speed.user_permissions.can_change_speed Boolean Puede cambiar la velocidad de ejecución
attire Object Opciones de vestimentas
attire.active String Nombre de la vestimenta seleccionada por default
attire.visible Boolean Mostrar la vestimenta por default
attire.user_permissions Object Permisos
attire.user_permissions.can_toggle_visibility Boolean Puede mostrar u ocultar la vestimenta
link String URL de un archivo adjunto (por ejemplo, la consigna en PDF).
initialDescription Boolean Muestra o no automáticamente la descripción al iniciar (default: true)
blocks Object Configuración para el editor de bloques. Consultar en gs-element-blockly
customErrors Object Mapeo de errores custom para bloques o código

Formato config.yml de vestimentas

Las vestimentas constan de un conjunto de reglas que deben cumplirse para que una celda se "vista" con cierta imagen (o texto). Ejemplo: (en JSON)

{
  "name": "Prueba",
  "rules": [
    { "when": { "blue": 0, "black": 0, "red": 0, "green": 0 }, "image": "Fondo.png" },
    { "when": { "blue": 0, "black": 2, "red": 0, "green": "*", "head": true }, "image": "Otra.png" },
    // exactamente dos negras, cualquier cantidad de verdes, sí o sí tiene que ser el cabezal

    { "when": { "blue": 0, "black": 2, "red": 0, "green": "*", "head": true }, "text": "hol" },
    // muestra el texto "hol" en vez de una imagen

    { "when": { "blue": "*", "black": "+", "red": 5, "green": "*", "head": false }, "image": "Más comodines.png" }
    // por lo menos una negra, cero o más azules y verdes, 5 rojas, y sí o sí tiene que *NO* ser el cabezal
  ]
}

Formato *.md

Es el Markdown de toda la vida. Se pueden usar emojis escribiendo su identificador entre dos puntos (:) - Lista completa.

Se pueden poner imágenes usando link a una imagen en base64. Para incluir imágenes que carguen rápido y puedan usarse offline, se recomienda poner el contenido en base64 directamente en el .md con <center>![La imagen en base64](data:image/png;base64,iV...)</center>. Conversor: https://www.base64-image.de/.

Tableros gobstones pueden ser renderizados usando las vestimentas del ejercicio. Ejemplo:

    <gs-board attire-src="mines">
      GBB/1.0
      size 4 3
      cell 1 2 Azul 0 Negro 1 Rojo 4 Verde 0
      cell 3 2 Azul 1 Negro 0 Rojo 5 Verde 1
      cell 3 1 Azul 1 Negro 0 Rojo 0 Verde 0
      cell 3 0 Azul 0 Negro 1 Rojo 0 Verde 0
      cell 2 2 Azul 0 Negro 0 Rojo 1 Verde 0
      cell 2 0 Azul 0 Negro 0 Rojo 0 Verde 1
      cell 2 1 Azul 0 Negro 6 Rojo 0 Verde 0
      head 2 1
    </gs-board>

Formato extra.gbs

Es código Gobstones con procedimientos y funciones que aparecerán en los ejercicios como "procedimientos primitivos" y "funciones primitivas". Las mismas pueden tener atributos:

  • nonatomic: Muestra los pasos intermedios en la ejecución paso a paso
  • tooltip: Descripción que aparecerá al pasar el puntero por encima
  • block_name: Nombre del bloque (sobreescribe la inferencia de nombres de bloque)
  • block_dropdown: Datos de opciones para convertir al único parámetro en un dropdown
  • block_icon: Imagen del icono del bloque en base64

Ejemplo de atributos

/*@ATTRIBUTE@tooltip@Pone una carta de cierto palo de un mazo de cartas españolas@*/
/*@ATTRIBUTE@block_name@JugarUnaDe_@*/
/*@ATTRIBUTE@block_dropdown@[("Bastos", 'Bastos'), ("Copas", 'Copas'), ("Espadas", 'Espadas'), ("Oros", 'Oros')]@*/
/*@ATTRIBUTE@block_icon@data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAFACAYA... etc etc etc@*/
procedure PonerCartaDe_(palo) {
  // ...
}

Inferencia de nombres de bloque

Para los procedimientos que no tengan el atributo block_name, se generará un nombre convirtiendo de camelCase a lenguaje natural. Por ejemplo, procedure UnProcedimientoDelDocente() {} generará el nombre de bloque Un procedimiento del docente.

Agujeros para argumentos

En los nombres de bloque se pueden poner guiones bajos (_) para representar los argumentos. Los bloques de llamadas a procedimientos/funciones usarán notación infija, y nombres como Poner_BolitasDeColor_ se traducirán en bloques de llamada como: screenshot

Bloques invisibles (auxiliares)

Si el nombre del procedimiento o función comienza con Aux o aux, respectivamente, no será visible para el alumno.

Ejecución paso a paso

En la ejecución paso a paso las acciones del docente son atómicas, mientras que las del alumno no. Para alterar este comportamiento, se pueden usar los atributos atomic y nonatomic.

Ejemplo en Gobstones SR

procedure Poner3Normal(color) {
    repeat (3) { Poner(color) }
}

/*@ATTRIBUTE@atomic@*/
procedure Poner3Atomico(color) {
    Poner3Normal(color)
}

program {
    Poner3Normal(Verde)
    Poner3Atomico(Rojo)
}

Ejemplo en Gobstones JR

<xml xmlns="http://www.w3.org/1999/xhtml"><variables></variables><block type="procedures_defnoreturn" id="K,vh!c_c,[5aAu][1N.(" x="316" y="27"><mutation isatomic="false"><arg name="color"></arg></mutation><field name="NAME">Poner3Normal</field><field name="ARG0">color</field><statement name="STACK"><block type="RepeticionSimple" id="9CG{4csXQe[W8bjqx.1J"><value name="count"><block type="math_number" id="6W7p$25K7B5H{8a.P~9o"><field name="NUM">3</field></block></value><statement name="block"><block type="Poner" id="$^%dtY8oN2o1tX;8/_!!"><value name="COLOR"><block type="variables_get" id="KpudN.sX#-B9/bv*X-YN"><mutation var="color" parent="K,vh!c_c,[5aAu][1N.("></mutation></block></value></block></statement></block></statement></block><block type="procedures_defnoreturn" id="s^tuL.~JeTwtfftwrH~a" x="325" y="210"><mutation isatomic="true"><arg name="color"></arg></mutation><field name="NAME">Poner3Atomico</field><field name="ARG0">color</field><statement name="STACK"><block type="procedures_callnoreturn" id="8oYVMe+Beps0PQ_dPi1E"><mutation name="Poner3Normal"><arg name="color"></arg></mutation><value name="ARG0"><block type="variables_get" id="v5smtPSGsJF/*kkUO6%#"><mutation var="color" parent="s^tuL.~JeTwtfftwrH~a"></mutation></block></value></block></statement></block><block type="Program" id="Phen~Gn:!??zS;Na`a$!" deletable="false" x="114" y="354"><mutation timestamp="1548369380888"></mutation><statement name="program"><block type="procedures_callnoreturn" id="/wxIJpk*e.(kZP+#j13L"><mutation name="Poner3Normal"><arg name="color"></arg></mutation><value name="ARG0"><block type="ColorSelector" id="$D=kRH,MlQ]n06%}+2Q!"><field name="ColorDropdown">Rojo</field></block></value><next><block type="procedures_callnoreturn" id="B.Pw(I{vdaVxd/EoonQa"><mutation name="Poner3Atomico"><arg name="color"></arg></mutation><value name="ARG0"><block type="ColorSelector" id="yp2c8in{}Oe+J^3B212f"><field name="ColorDropdown">Verde</field></block></value><next><block type="procedures_callnoreturn" id="!(FLw1ThEvoI.2[=!][t"><mutation name="Poner3Atomico"><arg name="color"></arg></mutation><value name="ARG0"><block type="ColorSelector" id="18tG*#!9WLI;/[-?wNpW"><field name="ColorDropdown">Negro</field></block></value></block></next></block></next></block></statement></block></xml>

En Gobstones JR, se puede convertir cualquier procedimiento en atómico haciendo botón derecho en la definición de un procedimiento, y activando o desactivando la opción Mostrar paso a paso.

Bloques disponibles

Hay una lista de bloques disponibles en el siguiente link:

https://github.com/Program-AR/gs-element-blockly/blob/dev/gs-element-blockly.html#L38

Bloques ocultos

Los siguientes bloques no se encuentran visibles por defecto:

  • DefinicionDeFuncionSimpleDeclarativa
  • DefinicionDeFuncionSimpleConParametrosDeclarativa
  • DefinicionDeFuncionDeclarativa

Se pueden activar usando el atributo blocks.defaultToolbox de meta.yml.

Mapeo de errores custom

En el campo customErrors de meta.yml se pueden transformar errores. Ejemplo:

  # Lista de transformaciones de errores...
  # Para ver los valores posibles de "block", "error", y los argumentos ("args") entregados por el intérprete, provocar un error y mirar el log en la consola del Chrome. Se puede interactuar con ellos usando el identificador lastError.
  - when:
      block: # (obligatorio) (lista, o string con nombre de bloque, o "*") bloques a los que afecta esta regla
        - Poner
      error: primitive-argument-type-mismatch # (obligatorio) # (lista, o string con código de error, o "*") errores que estamos queriendo capturar
      condition: args[4].typeName === "Dir" # (opcional) condición que tienen que cumplir los argumentos del error para que la regla se ejecute
    transform: args[4] = args[4].toString().replace("Dir:", "") # (opcional) transformación a ejecutar sobre los argumentos del error
    message: Poner recibió un <%=arg4%>, ¡¡cómo le vas a mandar una dirección al Poner!! # (obligatorio) mensaje de error a mostrar, soporta interpolar los argumentos del error (<%=arg0%>, <%=arg1%>, <%=arg2%>, etc
  - when:
      block: RepeticionCondicional
      error: primitive-argument-type-mismatch
    message: Todo mal, el repetir hasta espera una condición, pero le llegó un <%=arg4%>
  - when:
      block: AlternativaSimple
      error: "*"
    message: El if pinchó!!! completalo bien

Cursos

Un curso es un repositorio de GitHub con un guides.json. Los cursos pueden tener defaults en la carpeta assets que luego los ejercicios pueden heredar. Ejemplo:

El archivo guides.json contiene un array de guías. Cada guía es un objeto:

{
  "name": "Nombre de la guía",
  "repo": "usuario/repositorio",
  "homeLink": "http://link.com/alManualDeLaGuía",
  "exercises": [
    {
      "id": "2.1.1",
      "name": "Simulando repartir caramelos",
      "path": "Proyectos/Cap.2/Simulando repartir caramelos"
    }
  ]
}

Lista global de cursos

La lista global de cursos que toma Gobstones Web está en https://github.com/gobstones/gobstones-web/wiki/Courses

Clone this wiki locally