Saat Yüzü
RehberiClock Face
Guide

clockface.json şema 3 ile gradyan, kart, canlı ilerleme, animasyon ve dinamik içerik kullanan özgür saat yüzleri tasarla. Eski şema 1/2 yüzleri de çalışmaya devam eder. Create expressive clock faces with clockface.json schema 3: gradients, cards, live progress, animation and dynamic content. Existing schema 1/2 faces remain compatible.

Saat YüzüClock Face Ekran EklentisiScreen Plugin

Yapay Zekâ ile ÜretBuild with AI

İndirilebilir şema 3 spesifikasyonu cihazın kabul ettiği tüm alanları ve çalışan bir örneği içerir. Bir yapay zekâya doğrudan yükleyip istediğin tasarımı tarif ederek geçerli clockface.json üretebilirsin. The downloadable schema 3 specification includes every accepted field and a working example. Upload it directly to an AI, describe your design and generate a valid clockface.json.

Saat Yüzü Spesifikasyonu (.md)Clock Face Spec (.md) Eklenti RehberiPlugin Guide

Dosya YapısıFile Structure

Bir saat yüzü, cihazda /clock_faces/<id>/ klasöründe yaşar. Market paketin şu dosyaları içerir: A clock face lives in /clock_faces/<id>/ on the device. A market package contains:

clockface.json — zorunlu. Yüzün tanımı (arka plan + elementler).required. The face definition (background + elements).
preview.jpg — 240×240 önizleme. bgImage kullanırsan tam-ekran arka plan olarak da çizilir.240×240 preview. If you use bgImage, it is also drawn as the full-screen background.
manifest.json — market kataloğu için meta (id, ad, sürüm, en düşük cihaz yazılımı sürümü...).catalog metadata for the market (id, name, version, minimum device software version...).
settings.json — cihazın ürettiği tema kaplaması (opsiyonel, bkz. Tema).device-generated theme override (optional, see Theme).

Market kataloğu manifest.json örneği:Market catalog manifest.json example:

{
  "id": "arda_neon_orbit",
  "name": "Arda Neon Orbit",
  "author": "Arda",
  "version": "1.0.0",
  "category": "digital",
  "tags": ["digital", "animated", "neon", "weather"],
  "target_resolution": "240x240",
  "preview_image": "preview.png",
  "min_firmware_build": 3379561,
  "requires": { "custom_clock_schema": 3, "supports_weather": true }
}

Kök AlanlarRoot Fields

clockface.json kökünde arka plan ve elements dizisi tanımlanır. Tuval her zaman 240×240, merkez 120,120.The clockface.json root defines the background and an elements array. The canvas is always 240×240, center 120,120.

AlanField	VarsayılanDefault	AçıklamaDescription
`bgColor`	`#000000`	Arka plan rengi (hex).Background color (hex).
`bgImage`	`false`	`true` ise aynı klasördeki `preview.jpg` tam ekran çizilir (gradyan/font içeren zengin yüzler için).If `true`, the folder's `preview.jpg` is drawn full-screen (for rich faces with gradients/fonts).
`bgGradient`	—	`from`, `to`, `direction` ve `steps` ile yatay/dikey renk geçişi (şema 3).Horizontal/vertical color transition using `from`, `to`, `direction` and `steps` (schema 3).
`bgPattern`	`SOLID`	`SOLID`, `GRID`, `DOTS`, `STRIPES_H`, `STRIPES_V`, `DIAGONAL`, `CHECKERBOARD`
`bgPatternColor`	`#333333`	Desen çizgi/nokta rengi.Pattern line/dot color.
`elements`	[ ]	Çizilecek eleman nesneleri dizisi (sırayla, üst üste).Array of element objects (drawn in order, layered).

Ortak Eleman AlanlarıCommon Element Fields

Her eleman bir type ve aşağıdaki ortak alanlardan bazılarını taşır:Every element has a type plus some of these common fields:

AlanField	VarsayılanDefault	AçıklamaDescription
`type`	—	Eleman tipi (zorunlu).Element type (required).
`x`, `y`	`120`	Konum (px). 0,0 = sol üst.Position (px). 0,0 = top-left.
`color`	`#FFFFFF`	Renk; `#RRGGBB` veya `RRGGBB`.Color; `#RRGGBB` or `RRGGBB`.
`size`	`2`	Metin boyut çarpanı (textSize).Text size multiplier (textSize).
`font`	`2`	Yerleşik font no: `1,2,4,6,7,8` (7 = 7-segment dijital).Built-in font no: `1,2,4,6,7,8` (7 = 7-segment digital).
`align`	`CENTER`	`LEFT`, `CENTER`, `RIGHT`
`width`, `height`	`50`	Şekiller ve ANALOG/ARC için boyut/yarıçap.Size/radius for shapes and ANALOG/ARC.
`opacity`	`100`	0–100; arka planla harmanlanır.0–100; alpha-blended with background.
`format`	—	TIME/DATE/şekil biçimini belirler (aşağıda).Sets TIME/DATE/shape format (below).
`showWhen`	`ALWAYS`	`ALWAYS`, `BLINK`, `SECOND_EVEN`, `SECOND_ODD`
`pulse`	`false`	`true` ise opaklığı iki saniyelik yumuşak döngüyle hareketlendirir.`true` animates opacity on a smooth two-second cycle.

TIME & DATE

TIME, format alanına göre saat çizer. Özel anahtarlar: HH:MM, HH:MM:SS, HH, MM, SS ve ANALOG. Bunların dışında herhangi bir strftime deseni de verilebilir.TIME renders the clock per format. Special keys: HH:MM, HH:MM:SS, HH, MM, SS and ANALOG. Any other strftime pattern also works.

{ "type": "TIME", "format": "HH:MM",  "x": 120, "y": 100, "font": 7, "size": 1, "color": "#00FF00" }
{ "type": "TIME", "format": "ANALOG", "x": 120, "y": 120, "width": 180, "color": "#FFFFFF" }

ANALOG modunda yarıçap = width / 2. showFace, showTicks, showSeconds ile parçaları açıp kapat; faceColor, hourColor, minuteColor, secondColor ile ayrı renklendir. DATE tam strftime kullanır.In ANALOG mode radius = width / 2. Toggle parts with showFace, showTicks, showSeconds; color them with faceColor, hourColor, minuteColor and secondColor. DATE uses raw strftime.

{ "type": "DATE", "format": "%a %d %b", "x": 120, "y": 160, "font": 2, "color": "#AAAAAA" }

WEATHER_ICON & WEATHER_TEMP

WEATHER_ICON hava ikonu çizer. format: SIMPLE (sembol) veya ANIMATED (animasyonlu güneş/bulut/yağmur/kar). WEATHER_TEMP anlık sıcaklığı derece ile yazar.WEATHER_ICON draws a weather icon. format: SIMPLE (glyph) or ANIMATED (animated sun/cloud/rain/snow). WEATHER_TEMP prints the current temperature with a degree sign.

{ "type": "WEATHER_ICON", "format": "ANIMATED", "x": 180, "y": 60 }
{ "type": "WEATHER_TEMP", "x": 120, "y": 200, "font": 4, "color": "#FFD27F" }

TEXT

İki dilli yüzler için text_tr/text_en kullan. Metne {time}, {date}, {temp}, {weather} yer tutucuları eklenebilir; biçimleri timeFormat/dateFormat belirler. maxWidth gerektiğinde yazıyı küçültür; shadowColor, shadowX, shadowY gölge ekler.Use text_tr/text_en for bilingual faces. Text accepts {time}, {date}, {temp} and {weather} placeholders, formatted by timeFormat/dateFormat. maxWidth shrinks text when needed; shadowColor, shadowX and shadowY add a shadow.

{ "type": "TEXT", "text_tr": "GUNAYDIN", "text_en": "GOOD MORNING",
  "x": 120, "y": 40, "font": 2, "size": 1, "color": "#FFFFFF", "align": "CENTER" }

ŞekillerShapes

Tüm şekiller format: "HOLLOW" ile içi boş çizilebilir (varsayılan dolu). Konum x,y şeklin merkezi/çapasıdır.All shapes can be drawn outlined with format: "HOLLOW" (default filled). x,y is the shape's center/anchor.

type	Kullanılan alanlarFields used	NotNote
`SHAPE_RECT`	`x,y,width,height`	Dikdörtgen. `HOLLOW` = çerçeve.Rectangle. `HOLLOW` = outline.
`SHAPE_ROUND_RECT`	`x,y,width,height,radius`	Yuvarlatılmış kart/dikdörtgen; `HOLLOW` destekler.Rounded card/rectangle; supports `HOLLOW`.
`SHAPE_CIRCLE`	`x,y,width`	`width` = yarıçap.`width` = radius.
`SHAPE_LINE`	`x,y,width,height`	Çizgi/çubuk. `format:"DASHED"` kesik. Yön: `width>height` ise yatay.Line/bar. `format:"DASHED"` for dashes. Direction: horizontal if `width>height`.
`SHAPE_TRIANGLE`	`x,y,width,height`	Tepe `(x, y−height)`, taban `±width`.Apex `(x, y−height)`, base `±width`.
`SHAPE_STAR`	`x,y,width`	5 köşeli yıldız; `width` = dış yarıçap.5-point star; `width` = outer radius.
`SHAPE_HEART`	`x,y,width`	Kalp; `width` = ölçek.Heart; `width` = scale.
`SHAPE_DIAMOND`	`x,y,width`	Eşkenar dörtgen; `width` = yarı köşegen.Diamond; `width` = half-diagonal.

{ "type": "SHAPE_CIRCLE", "x": 120, "y": 120, "width": 90, "format": "HOLLOW", "color": "#1E4A7A" }
{ "type": "SHAPE_RECT",   "x": 40, "y": 200, "width": 160, "height": 6, "color": "#E8281E" }

SHAPE_ARC — halka / gösterge— ring / gauge

Yay/halka çizer; gösterge ve ilerleme efektleri için idealdir. 0° tepededir, saat yönünde artar.Draws an arc/ring; ideal for gauges and progress effects. 0° is at the top, increasing clockwise.

AlanField	AçıklamaDescription
`width`	Dış yarıçap.Outer radius.
`height`	İç yarıçap (`0` = dolu pasta dilimi).Inner radius (`0` = filled pie).
`start`, `end`	Başlangıç/bitiş açısı (derece).Start/end angle (degrees).
`bind`	`seconds` / `minutes` / `hours` → bitiş açısı canlı saate göre hareket eder.`seconds` / `minutes` / `hours` → end angle animates with the live clock.

{ "type": "SHAPE_ARC", "x": 120, "y": 120, "width": 110, "height": 100,
  "start": 0, "bind": "seconds", "color": "#E8281E" }

PROGRESS_BAR & Şema 3 Tasarım AraçlarıSchema 3 Design Tools

PROGRESS_BAR, x,y noktasından başlayan yuvarlatılmış doğrusal göstergedir. bind: seconds, minutes, hours veya day; statik gösterge için value/max kullan. trackColor boş kısmı, color dolu kısmı belirler.PROGRESS_BAR is a rounded linear gauge starting at x,y. Set bind to seconds, minutes, hours or day; use value/max for a static gauge. trackColor colors the track and color the fill.

{ "type": "PROGRESS_BAR", "x": 28, "y": 190, "width": 184, "height": 7,
  "radius": 4, "bind": "seconds", "max": 59,
  "trackColor": "#27324F", "color": "#63E6FF" }

Tema KaplamasıTheme Override

Aynı klasördeki settings.json bir tema taşıyabilir. Varsa bg arka planı, color ise tüm eleman renklerini ezer (uygulamadaki "Hazır Temalar" bunu kullanır). bgImage kullanan yüzlerde tema uygulanmaz.A settings.json in the same folder may carry a theme. If present, bg overrides the background and color overrides every element color (the app's "Preset Themes" use this). Theme is not applied to faces using bgImage.

{ "bg": "#101010", "color": "#00E5FF" }

Tam ÖrnekFull Example

{
  "requires": { "custom_clock_schema": 3 },
  "bgColor": "#08111F",
  "bgGradient": { "from": "#08111F", "to": "#241044", "direction": "VERTICAL", "steps": 60 },
  "elements": [
    { "type": "SHAPE_ROUND_RECT", "x": 18, "y": 62, "width": 204, "height": 112, "radius": 18, "color": "#101B34", "opacity": 92 },
    { "type": "TEXT", "text": "{time}", "timeFormat": "%H:%M", "x": 120, "y": 104, "font": 7, "size": 2, "maxWidth": 190, "color": "#FFFFFF", "shadowColor": "#000000", "shadowX": 3, "shadowY": 3 },
    { "type": "TEXT", "text": "{date}  {temp}°", "dateFormat": "%d %b", "x": 120, "y": 148, "font": 2, "color": "#B9C8FF" },
    { "type": "PROGRESS_BAR", "x": 28, "y": 190, "width": 184, "height": 7, "radius": 4, "bind": "seconds", "max": 59, "trackColor": "#27324F", "color": "#63E6FF" },
    { "type": "SHAPE_CIRCLE", "x": 120, "y": 216, "width": 3, "color": "#63E6FF", "pulse": true }
  ]
}

Sınırlar & İpuçlarıLimits & Tips

Şema: Yeni özellikler için kökte ve market manifestinde requires.custom_clock_schema: 3 belirt. Eski yüzler değişmeden çalışır.Schema: Declare requires.custom_clock_schema: 3 at the root and in the market manifest for new features. Existing faces remain compatible.
Element: Bir yüzde en fazla 64 element kullanılabilir.Elements: A face can contain at most 64 elements.
Boyut: clockface.json ≈ 64 KB, preview.jpg ≈ 160 KB sınırı.Size: clockface.json ≈ 64 KB, preview.jpg ≈ 160 KB limit.
Tuval: her zaman 240×240. ~8–12 px güvenli kenar boşluğu bırak, taşma yapma.Canvas: always 240×240. Keep ~8–12 px safe margin; avoid overflow.
Performans: resim-tabanlı (bgImage) yüzler ~250 ms'de bir yeniden çizilir; animasyon için JSON elementlerini tercih et.Performance: image-based (bgImage) faces redraw ~every 250 ms; prefer JSON elements for animation.
Renkler RGB565'e dönüştürülür; ince ton farkları kaybolabilir.Colors are converted to RGB565; subtle shades may be lost.

Test: JSON'ı uygulamadan cihaza yayınla; parse hatasında ekranda "JSON Parse Error" görürsün. Tek/çift haneli saat, saniye animasyonu ve taşmayı cihazda doğrula. Testing: publish the JSON to the device from the app; on a parse error the screen shows "JSON Parse Error". Verify single/double-digit hours, second animations and overflow on the device.

PUCKS

Eklenti mi geliştiriyorsun?Building a plugin?

Bildirim ve dashboard eklentileri için manifest & schema rehberine göz at.Check the manifest & schema guide for notification and dashboard plugins.

Eklenti RehberiPlugin Guide Tüm ÖzelliklerAll Features